J. TERRY GODFREY 


rrogrammin 


the Q)S/ 
Kernel 


OPEN PRINTER 
DEVICE 


N 
INCREMENT CLOSE PRINTER 
LINE COUNT DEVICE 
LOAD ' EXIT 


PRINTER ARRAY | 


PRIVATE SYSTEM BUS PUBLIC SYSTEM BUS 


PRIVATE PROCESSING 


MEMORY : MODULE 


BUS / SYSTEM 


PRIVATE VO | | BUS | ae | ) 
) [| conTROLLeR _ a3 _— P| controwen ie = MEMORY 


CONTROLLER 


INCREMENT 


ROW POINTER SYSTEM I/O 
TEM I 


CONTROLLER 


LOCAL BUS 


| PRINTER BUFFER 


PROCESSING 


) DIRECT =| | 


; 
LOAD | 
’ 
| 


MEMORY | PROCESSOR | ec  e / MODULE 
cer , | ’ XTEN @) ; ee 
A | ACCESS (DMA) | | EXTENSION | Jb 


| CONTROLLER | : 


WRITE 
PRINTER BUFFER 


INCREMENT BUFFER 
POSITION 640 


Programming 
the O3$/2 Kernel 


Programming 
the O3/2 Kernel 


J. Terry Godfrey 


President, JTG Associates 


PRENTICE HALL 
Englewood Cliffs, New Jersey 07632 


Library of Congress Cataloging-in-Publication Data 


Godfrey, J. Terry 
Programming the OS/2 kernel / J. Terry Godfrey. 
p. cm. 
ISBN 0-13-723776-6 
1. OS/2 (Computer operating system) Fe Fit te. 
QA76.76.063G63 1991 
005.4' 469--dc20 90-7518 
CIP 


Editorial/production supervision and 
interior design: Kathleen Schiaparelli 
Cover design: Wanda Lubelska 
Manufacturing buyer: Lori Bulwin/Linda Behrens/Patrice Fraccio 


© 1991 by Prentice-Hall, Inc. 
A Division of Simon & Schuster 
Englewood Cliffs, New Jersey 07632 


The author and publisher of this book have used their best efforts in preparing this book. These efforts 
include the development, research, and testing of the theories and programs to determine their 
effectiveness. The author and publisher make no warranty of any kind, expressed or implied, with regard 
to these programs or the documentation contained in this book. The author and publisher shall not be 
liable in any cvent for incidental or consequential damages in connection with, or arising out of, the 
furnishing, performance, or use of these programs. 


UNIX is a registered trademark of AT&T (Bell Laboratories). 

Apple and MacIntosh are registered trademarks of Apple Computer, Inc. 

Intel is a registered trademark of Compuview Products, Inc. 

Microsoft Window is a trademark and Microsoft is a registered trademark of the Microsoft Corporation. 
IBM and IBM PC/XT/AT are registered trademarks of International Business Machines Corporation, 


All rights reserved. No part of this book may be reproduced, in any form or by any means, without 
permission in writing from the publisher. 


Printed in the United States of America 


1098 765 43 2 1 


ISBN O-13-?23??b-b 


Prentice-Hall International (UK) Limited, London 
Prentice-Hall of Australia Pty. Limited, Sydney 
Prentice-Hall Canada Inc., Toronto 

Prentice-Hall Hispanoamericana, S.A., Mexico 
Prentice-Hall of India Private Limited, New Delhi 
Prentice-Hall of Japan, Inc., Tokyo 

Simon & Schuster Asia Pte. Ltd., Singapore 

Editora Prentice-Hall do Brasil, Ltda., Rio de Janeiro 


To Judy, Ray, Agnes, and Emma 


Contents 


PREFACE 


Part | Introduction to OS/2 
1 THE OS/2 ENVIRONMENT 


1.1 


1:2 


1.3 
1.4 


Hardware Considerations 3 


yy EP 
1.1.2 
1.1.3 


The 80286 and 80386 Architecture, 3 
Hardware Operation for Protected Mode, 8 
Software Operation for Protected Mode, 12 


A Brief Look at Operating System/2 14 


1.2.1 


Protected Mode, 17 
API Services, 19 
Memory Management, 29 


Multitasking, 29 


Version 1.0 and 1.1 Differences, 30 


The OS/2 Presentation Manager 31 
Summary 35 


References 36 
Problems 37 


xi 


vii 


viii Contents 


Part Il Programming OS/2 Using Assembler 40 
2 INTRODUCTORY OS/2 ASSEMBLER 
PROGRAMMING 40 
2.1 OS/2 Services: Accessing the API 40 
2.2 Introductory Assembler Programming 43 


2.2.1 The IBM Macro Assembler/2, 43 
2.2.2 An Example Program: Printer Control, 45 


2.3 Accessing the Video Services 51 


2.3.1 The Display Buffer, 51 

2.3.2 Locking the Screen Context, 54 

2.3.3 Printing the Graphics Screen under 

OS/2, 62 

2.3.4 Connecting Line Graphics with OS/2, 74 
2.4 Software Design 87 
2.5 Summary 88 

References 89 


Problems 89 


3 MEMORY MANAGEMENT AND MULTITASKING 
WITH ASSEMBLER 93 


3.1 Memory Management and Multitasking 93 
a2 Memory Management Activities 96 


3.2.1 Creating and Accessing Memory Segments, 96 
3.2.2 Creating and Accessing a Shared Segment, 105 
3.2.3. Changing Segment Size, 115 

3.2.4 Creating and Accessing Huge Segments, 119 
3.2.5. Suballocating Memory, 125 


3.3 Multitasking 129 


3.3.1 Semaphores, 129 
3.3.2 Creating a Thread, 130 
3.3.3 Creating Another Process, 140 


3.4 Interprocess Communications 150 


3.4.1 Pipes and Queues, 150 
3.4.2 Shared Memory Segments, 163 


3.5 Summary 163 
References 164 
Problems 164 


Part Ill 


Contents 


5 


Advanced OS/2 Kernel Programming 
4 OS/2 andC 


4.1 


4.2 


4.3 


4.4 


4.5 


Higher Levels of Abstraction 167 


4.1.1 The C Include Files, 168 
4.1.2 The Low-Level Nature of the API, 169 
4.1.3 Comparison of C with Assembler, 170 


Introductory C Programming with OS/2 171 


4.2.1 C Program Architecture and Structure, 171 
4.2.2 Accessing the API from C, 173 

4.2.3. Graphics Using C and OS/2, 178 

4.2.4 Low-Level Access for Printer Graphics, 182 


Memory Management and Multitasking 
with C 188 


4.3.1 Creating and Accessing Segments, 192 
4.3.2 Creating a Thread or Process, 197 


Other Programs 200 


4.4.1 A Rotating Tetrahedron, 200 
4.4.2 Plotting Dow Jones Activity, 204 


Summary 217 
References 217 
Problems 217 


ADDITIONAL OS/2 CONSIDERATIONS 


5.1 
5.2 


5.3 


5.4 


ee, 


Mixed-Language Programming and OS/2 222 
Dynamic Linking and Resource Management 226 


5.2.1 Using Dynamic Linked Libraries, 227 
5.2.2 The Definition File, 227 

5.2.3 Creating a DLL, 231 

5.2.4 DLL Examples, 232 


Optimizing the C Design Process 239 


5.3.1 Top-Down Design, Structured Programming, and 
Modular Code, 240 

5.3.2 Templates, Style, and Form, 246 

5.3.3 API Return Values and Error Checking, 250 


Reexamining the Core versus Presentation Manager 
API Services 251 


Advanced C Example: A Three-Dimensional Surface 251 


221 


5.6 Summary 267 
References 267 
Problems 268 


APPENDICES 


A 
B 
C 


IBM MACRO ASSEMBLER/2 
MICROSOFT C COMPILER VERSION 5.1 


FUNCTION DEFINITIONS AND MACROS 
USED TO INTERFACE THE API 


PROGRAMS USED IN THIS BOOK 
KEYBOARD AND MOUSE KERNEL FUNCTIONS 


ANSWERS TO PROBLEMS 
INDEX 


Contents 


270 
270 
293 


300 
310 
313 


317 
331 


Preface 


This book has been developed for teaching programming using the IBM Operating 
System/2 (OS/2). It is suitable for a one-semester course in OS/2, as an adjunct to 
a course in operating system design, or as a vehicle for self-study on OS/2 program- 
ming. The emphasis in the book is on programming techniques for an advanced 
- multitasking microcomputer operating system. Both Macro Assembler/2 and the C 
language are supported in the text. The OS/2 Application Programming Interface 
(API) services can be understood in either context. 

The text addresses the basic OS/2 kernel services: the video (Vio), Disk 
Operating System (Dos), keyboard (Kbd), and mouse (Mou) API functions. The 
latter service is most useful in a windowed display such as the Presentation Man- 
ager, which is omitted from this text. The book concentrates on the OS/2 Full- 
Screen Command Mode, which utilizes the entire display for presentation of a single 
program, making no other programs visible. Similarly, input and output under pro- 
gram control is implemented through the standard assembler or C syntax, such as 
printf() or scanf(). These operate in Protected Mode as well as Real Mode. Conse- 
quently, there is little need to incorporate specific keyboard API services into the 
program examples. Keyboard and mouse functions are discussed briefly in Appen- 
dix D. Some use is made of the keyboard services, for example, to pause the graph- 
ics screen. | 

The Presentation Manager windowed interface is not developed in this book. 
Although this is a rich and complex interface, it is not considered suitable for a one- 


xi 
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semester course on OS/2 programming. The services at the level of IBM’s OS/2 
Standard Edition 1.0 are assumed as sufficient material for such an introductory 
course. When object-oriented programming tools become available for the Presenta- 
tion Manager and the burden for programming this interface is eased, it will be ap- 
propriate in a beginning course in OS/2 programming. 

During the late 1980s when OS/2 was developed, the principal major compet- 
ing operating system for advanced microcomputer applications was UNIX. OS/2 
follows IBM’s earlier microcomputer operating system, Disk Operating System 
(DOS), and runs DOS as a subset. UNIX has tended to be used more within the 
scientific and engineering community and is generally optimized for larger machines 
than the baseline microcomputers developed during this time frame. 

What are the advantages afforded by OS/2? OS/2 is predominantly a multi- 
tasking operating system capable of extensive memory management. It accomplishes 
these activities through hardware intervention based on the Intel 80286 chip set. 
(Hardware compatibility exists at the 80386 and 80486 levels.) There are four lev- 
els of protection provided (unlike the Motorola 68020 and 68030, for example, 
which have two); hence OS/2 can be tailored to handle the multitasking problem. 
The protection mechanisms provide coarse-grained through fine-grained memory 
management. This allows a detailed dynamic memory allocation at any given time. 

If we examine OS/2 in the framework of the near-term evolution of microcom- 
puter systems (1990s), it is apparent that changes in software development and 
applications will dictate about an order-of-magnitude increase in software complex- 
ity. It is clear that many efforts will give way to multithread and multiprocessor pro- 
gramming. The OS/2 multitasking features make it a good candidate for major 
microcomputer applications during the 1990s time frame. Also, the hardware protec- 
tion mechanisms mentioned above are suited for minimizing operational errors in 
such multitasking situations. Hence OS/2 is positioned to become the operating 
system of choice for high-end personal computer applications based on the Intel chip 
sets. 

OS/2 is particularly suited for user-friendly operation and programming. The 
API services are readily programmed in a fashion similar to the now-more-familiar 
Basic Input Output System (BIOS) interrupt calls. The Presentation Manager repre- 
sents a large-scale object-oriented interface. It is programmed in an almost identical 
manner to the Microsoft Windows Software Development kit (SDK) programming. 
OS/2 is moving rapidly toward widespread acceptance as the IBM microcomputer 
operating system for the early 1990s, just as DOS was for the 1980s. 

This book is intended to teach techniques on how to program in an advanced 
multitasking environment. The approaches required for software development reflect 
the solutions and compromises that exist in the 80286 hardware and the OS/2 Pro- 
tected Mode software. The power of OS/2 lies in its potential to run a number of 
large-scale applications simultaneously, with asynchronous and synchronous sharing 
of data. The use of pipes, queues, and semaphores (as well as shared memory 
blocks) ensures that intertask communication minimizes errors and follows well- 
established guidelines. 
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OS/2 is large, but experience has demonstrated a rather elegant superstructure 
that combines Microsoft Windows, DOS, multitasking, and memory management. 
Even in the scaled-down 80286 environment, OS/2 presents a very user-friendly 
interface to the hardware. Finally, all the programming skills developed for the 
earlier DOS framework are applicable when writing software for OS/2. IBM and 
Microsoft have maintained many philosophical features of DOS while incorporating 
the Apple MaclIntosh-like graphical interface in PM. OS/2 is truly an order-of- 
magnitude change in microcomputer operating systems. The potential for large-scale 
object-oriented applications is intrinsic to the PM definition. 

This, then, is the world of OS/2 as we move through the 1990s. The reader 
can expect a programming arena in which multitasking is important. This is a pre- 
cursor to the parallel processing systems coming toward the end of the decade. At 
the same time, implementation of segmented large-scale applications becomes a 
reality through interprocess communications and memory management. Thus effi- 
cient use of microcomputer resources becomes feasible. Finally, graphical interface 
techniques lead to very user-friendly application environments. OS/2 promises to be 
at the forefront of microcomputer operating systems because of all these features. 

One comment about the style used in this book. The IBM macro calls to the 
Application Program Interface (API) are used throughout. This is in keeping with the 
trend toward higher-level-language constructs and structured code when developing 
assembler programs. It does have the effect of obscuring the stack loading during an 
API call and assumes that the reader has access to the IBM API macros (i.e., the 
IBM Toolkit include files). The trade-off, however, is that fewer lines of program 
code need to be understood, and for someone familiar with the calls, the inferences 
are clear. This has implications for maintenance as well as debugging. 

This text is practically oriented. The examples are somewhat lengthy, by inten- 
tion and as a real-world case would be. They are intended for the serious student 
who is interested in programming under OS/2. The Color Graphics Adapter mode 
(CGA) is illustrated because of its relative simplicity and ease of programming. 
Also, it is a readily testable feature that can easily be programmed using C or as- 
sembler. The book assumes that the student has a basic familarity with C and as- 
sembler. 
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| The OS/2 Environment 


During the 1980s, IBM developed (in conjunction with Microsoft, Incorporated) the 
Disk Operating System (DOS) [1] as a primary operating system for its family of 
microcomputers: the IBM PC, XT, XT286, AT, PS/2 Models 25, 30, 50, 60, 70, and 
80. These systems were developed using the Intel family of central processor unit 
(CPU) chips, including the 8086, 8088, 80286, and 80386 [2-4]. DOS is a single- 
thread single-user system and hence is capable of executing only one task at any 
given time. Intel, however, provided the 80286 and 80386 with architectures that 
ensure hardware protection for multiple applications. This prevents code segments 
from being mixed during execution of multiple separate tasks. Such multitasking is 
the framework required by the advanced applications in existence and slated to 
arrive throughout the decade of the 1990s. 

Toward the end of the 1980s a clear need developed for an operating system 
that was capable of supporting and utilizing these advanced microcomputer hardware 
architectures. In response to this need, IBM and Microsoft developed Operating 
System/2 (OS/2) as their candidate to run on the Intel 80286-based (and 80386) 
machines [5,6]. There are many facets to OS/2. Both IBM and Microsoft have 
provided information needed to be able to program in the OS/2 environment through 
their Toolkit (IBM) [7] and Software Development Kit (Microsoft) [8]. Initially, 
following an early issue by Microsoft in 1987, IBM released OS/2 Standard Edition 
Version 1.0 in December 1987. This early version employed the full-screen com- 
mand prompt mode only, which initially displays a menu followed by a screen with 
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header. Basically, two modes were allowed: DOS compatibility mode, which runs 
from a screen with a typical prompt such as 


(C:\>) 
and runs DOS programs, and OS/2 Protected Mode, which runs from a screen with 
a typical prompt such as 

[C:\>] 
In the fall of 1988 IBM released Version 1.1 of the Standard Edition, which in- 
cluded the Presentation Manager (PM) [9]. This provided a full Windows-like gra- 
phical interface to the user. This graphical interface is very similar to that found 
with the Apple MacIntosh operating system [10]. 

In addition to the Standard Editions, IBM and Microsoft have developed an 
Extended Edition, which has a local area network (LAN) interface and a database 
manager with support for Structured Query Language (SQL). The later editions of 
OS/2 (Extended Edition 1.0-10/88 and 1.1-11/88) function in essentially the same 
fashion as the Standard Edition; hence we will focus on the Standard Edition and 
not address the LAN and database features in this book. Basically, we are interested 
in programming highlights rather than specialized application packages. 

IBM recommends a minimum of 2 megabytes (MB) of random access mem- 
ory (RAM) for running Standard Edition 1.0, 3 MB of RAM for Version 1.1, and 
3 MB of RAM for the Extended Edition (EE). Also, the EE may completely con- 
sume a 20-MB hard disk drive [11]. Most versions of OS/2 come complete with 
the CodeView debugger, which is capable of debugging both assembler and C code. 
These are the two languages considered in this book. The language support for 
OS/2 is extensive with assembler, FORTRAN, BASIC, C, Pascal, and COBOL 
compilers existing. As indicated, we will focus on C [12] and assembler [13] for the 
OS/2 environment. Although IBM provides a Protected Mode editor with Version 
1.1, in the program development for this book, VEDIT PLUS [14] was used as a 
full-screen editor run from the DOS compatibility box. This process was quite 
smooth and allowed for early development when only Version 1.0 was available. 
Context switching between Real (DOS compatibility box) and Protected Mode was 
accomplished rather efficiently in the OS/2 implementation. Programming the Pres- 
entation Manager graphical interface is very much a Windows-like exercise [15]. 

With these introductory remarks in mind, where are we going with this book? 
The goal is to establish for the reader the capability to write programs in the OS/2 
kernel environment. We address code development in assembler (IBM Macro As- 
sembler/2) and C (Microsoft C Compiler Version 5.1). 

What is so unusual about OS/2 in relation to conventional Real Mode (Intel 
80286 Real Mode) programming? In OS/2 the major achievement is the definition 
of API services for access of the Protected Mode multitasking and memory manage- 
ment features. Typically, an entire new class of function calls is added to the usual 
assembler or C code. These functions (the inns constitute the system interface and 
have syntax (in ASM) like 
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@DosExit action, result 


instead of the normal return instruction, ret, or 


@VioScrLock waitf,iostat,viohdl 
@VioGetPhysBuf PVBPtrl,viohdl 


@VioScrUnLock viohdl 


instead of int 10H. Hence it is apparent at a glance that OS/2 function calls tend to 
require more parameters (versus register setup) than conventional assembler. They 
have the added attribute, however, of being a symbolically elegant interface. By the 
latter reference, we mean that the API services appear as a natural extension of 
assembler or C code in modular and complete fashion. 

OS/2 is a model operating system for illustrating advanced features in a sys- 
tems software framework. As discussed, it is somewhat RAM intensive, although it 
will run comfortably with 2 MB as an installed base. The principal accomplishment 
is the segregation of services for operation in the multitasking environment. How 
this segregation is accomplished is reflected in the programming techniques used to 
write code for OS/2. OS/2 is a good example of how multitasking should be imple- 
mented. 


1.1 HARDWARE CONSIDERATIONS 


OS/2 is written primarily for the architecture of the Intel 80286 (and is compatible 
with the 80386) as it exists in Versions 1.0 and 1.1 of the Standard and Extended 
Editions. The manner in which the hardware and software coexist depends largely 
on the Intel concept of segmented memory and the notion of levels of protection. 
We examine these aspects of OS/2 and attempt to correlate the register-level hard- 
ware with OS/2 address allocation. It is important to recognize, however, that keep- 
ing with the Intel philosophy of downward compatibility, subsequent microproces- 
sors in the 8086 family run code intended for the earlier chip sets. Hence the 80386 
architecture, although more advanced than the 80286, will support 80286 Protected 
Mode software. This means that OS/2 runs on 80386 machines as well. 


1.1.1 The 80286 and 80386 Architecture 


It is worthwhile examining the Intel 80286 (and 80386) architecture at this point 
because this implementation serves as the basis for development of programs such 
as OS/2. Once we have touched on this hardware foundation, we can forever assume 
that a starting point exists from which to explore the features of 80286 systems 
software. 

Intel started the 8086 family of microprocessors with initial entries that have 
16-bit addressing. This includes the 8086, 8088, and 80286 chips. The 80386 has 
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32-bit addressing and represents a major step forward, in keeping with the increased 
speed of these integrated circuits. What is the major limitation of the 16-bit archi- 
tecture? In a physical sense (based on the actual wiring of circuits and memory) 16 
bits provides only 2!° or 65,536 possible individual references. This is the usual 64K 
segment. Recognizing that this constituted a very limited memory capability, Intel 
expanded the addressing concept to allow for multiple segments by providing a set 
of segment registers used to hold segment addresses. (This was in addition to the 
16-bit instruction pointer that held an offset into the code segment, for example.) 
When IBM implemented the Real Mode operating system DOS, a 1-MB address 
limit was built into the architecture which was based on a 20-bit address. Address- 
ing was accomplished by shifting the segment address left 4 bits, appending a zero 
(hexadecimal) to the segment address, and adding the offset to get the five-digit 
hexadecimal physical address. For example, assuming a segment address 1O0AF and 
an offset FOFF this physical address is 


10AFO _ = (segment address) 
FOFF (offset address) 
1FBEF — (physical address) 
where the usual notation would be 1OAF:FOFF. What are the register structures used 


to support this addressing scheme? In the 8086 and 8088 the following registers 
exist: 


Data 


AX the Accumulator: This register can be used for general programming 
storage. 


BX the Base Register: This register is frequently used to hold address val- 
ues when accessing memory. 


CX the Count Register: During loop operations this register holds the 
count index. 


DX the Data Register: This register is used for general storage. 
Segment 
CS the Code Segment Register: This register points to the beginning of 


the code segment block. 


DS the Data Segment Register: This register points to the beginning of 
the data segment block. 


SS the Stack Segment Register: This register points to the beginning of 
the stack segment block. 


ES the Extra Segment Register: This register points to the beginning of 
the extra segment block. 
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Pointer 
SP the Stack Pointer: This register holds offset values for the stack. 
BP the Base Pointer: This register holds offset values into the data seg- 
ments. 
Index 
SI the Source Index: This register holds an index offset in memory and 
frequently references the instruction source. 
DI the Destination Index: This register holds an index offset in memory 


and frequently references the instruction destination. 


Added to these 12 registers are the instruction pointer (IP) and flags registers, yield- 
ing a total of 14 16-bit registers for the 8088 and 8086. 
The 80286 enhances this register set with the addition of five registers: 


GDTR the Global Descriptor Table Register: This register points to system 
resource segments. 


IDTR the Interrupt Descriptor Table Register: This register points to inter- 
rupt service routine segments. 


LDTR the Local Descriptor Table Register: This register points to the 
active local program code segment. 


TR Task Register: This register holds the code segment address for the 
current task. 


MSW the Machine Status Word Register: This register sets up the proc- 
essing for real or Protected Mode. 


These Protected Mode registers plus some others are used by the operating system 
to provide proper address allocation during execution of an active Protected Mode 
task. 

Figure 1.1 illustrates a typical 80286 central processor unit (CPU) environment. 
Here the parallel external bus structure is apparent. The 80286 control of both the 
private and public system buses is via bus controllers (typically, an Intel 82288 and 
82289 combination). In the IBM AT and PS/2 Model 50 and 60 such a bus struc- 
ture exists with a representative architecture as depicted in Figure 1.2. Both these 
figures are similar and illustrate the parallel bus structure typical of 80286 systems. 
The private system bus contains localized private input/output (I/O) processing and 
buffering such as RS-232C adapters and video adapters, which constitute external 
physical entities. These are frequently accessed using direct memory access (DMA) 
controllers. The 8259A programmable interrupt controller (PIC) interfaces external 
hardware interrupts to the CPU. Both the private and public system buses have a 
three-part architecture: a control, address, and data bus subset. Control bus interfaces 
are handled by an 82288 bus controller with associated address decode logic (this is 
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typically implemented using LS138 decoder/demultiplexers) [16,17]. The address 
V/O is handled using latches, which hold and strobe address data onto the system 

_ buses in response to enable signals. Finally, data is placed on the data bus using 
transceivers (typically, the LS245 transceiver). 


PRIVATE SYSTEM BUS PUBLIC SYSTEM BUS 

| er o- 

ME | er o- 

ES Te) po | oom | 

ES conn contin | oom | 

Ey Me) 
Ey 
LOCAL (oT OOo 
AIRECE er | 
MEMORY PROCESSOR oe 
ACCESS (DMA) EXTENSION 


CONTROLLER 


Figure 1.1 Representative 80286 system environment illustrating local and system buses. 


Figure 1.3 illustrates a representative memory and port allocation of address- 
ing among public and private spaces. For low memory, a 1-MB partition is illus- 
trated from 0H to OFFFFFH (here H indicates hexadecimal). This corresponds to the 
DOS partition in the IBM microcomputer address space. Local firmware is illustrated 
at the top end of the 16-MB physical memory space (OFFFOOOH to OFFFFFFH). 
This would be in the OS/2 extended memory area. In the IBM systems, erasable 
programmable read-only memory (EPROM) exists between portions of the 640K and 
1-MB address area, in what is designated as private system memory in Figure 1.3. 
Finally, the bulk of the public system memory resides above 1 MB. In OS/2 imple- 
mentations, this extended memory exists from 1 MB to 16 MB. 

The 80386 uses double-word arithmetic. The eight general registers are 32-bit: 
EAX, EBX, ECX, EDX, ESI, EDI, ESP, and EBP. The prefix E indicates that the 
familiar 16-bit general registers (AX, BX,...) have simply been extended to 32 bits. 
In fact, the low-order word of each of these eight registers can be treated as the 
equivalent 16-bit register with all the reserved name definitions applied to these 16- 
bit quantities. (The data registers further subdivide into byte-length register halves 
AH, AL, BH, BL, ....) Clearly, this implies a downward compatibility for running 
16-bit microprocessor (8088, 8086, and 80288) code. 

The instruction pointer (EIP) and flags register (EFLAGS) have similar down- 
ward compatibility features. Finally, there are six segment registers: CS, DS, ES, SS, 
FS, and GS. The last two are new and provide for additional independent data 
segment access using overrides. These segment registers are each of word length. In 

addition to the registers specified, we have the following new system register types 
(plus the memory-management registers specified above): 


INTERRUPT LINES (!RO-IR5) 


LOCAL BUS 


8259A 
INTR_| PROGRAMMABLE 
INTERRUPT 
CONTROLLER 


82284 
CLOCK 


GENERATOR 
PRIVATE SYSTEM BUS PUBLIC SYSTEM BUS 


80286 
CPU 


82289 BUS 
ARBITER 


82288 BUS 82288 BUS 
CONTROLLER CONTROLLER 
ADDRESS 
ee e DECODE ee e 
8283/83 8283/83 


LATCHES 


LATCHES 
ADDRESS 


DATA 


8286/87 
TRANSCEIVERS 


8286/87 
< | transceivers K > 


Figure 1.2 Expanded view of the 80286 bus environment. 
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1, Control registers (four): CRO, CR1, CR2, CR3 


2. Debug and test registers (eight): DRO, DR1, DR2, DR3, DR4, DRS, DR6, 
DR7 


MEMORY ADDRESS 
SPARE 


FFFFFFH 
LOCALERROR lerroooy 


PORT ADDRESS 
SPARE 


PUBLIC CEEEH 


SYSTEM 


MEMORY PUBLIC 


VO 


100000H 100H 


PRIVATE 
SYSTEM 
MEMORY 


PRIVATE 
VO 


OH 


Figure 1.3 Representative memory and port allocation among private and public 
address spaces. 


What does all this mean in terms of OS/2? Basically, the hardware manipula- 
tion of addressing under OS/2, and established by the link/locate operation in re- 
sponse to programmed instruction sequences, must occur so that no segment viola- 
tions take place in system memory. This is the topic of the next two subsections, 
where operation is described for a Protected Mode installation. We will observe that 
the 80286 registers are the primary vehicle for ensuring Protected Mode isolation of 
tasks. 


1.1.2 Hardware Operation for Protected Mode 


The main system memory of an 80286 system is organized as a sequence of 8-bit 
addressable quantities called bytes. The addressing spans the range 0 to 27° (1 MB) 
in Real Address Mode and up to 2*4 (16 MB) in Protected Mode. In Protected Mode 
no direct access to physical memory is allowed. The physical address space, for 
example, is controlled by 24 address pins from the 80286 chip itself. This dictates 
the 16-MB physical limit. Composition of the address space in Protected Mode, 
however, indicates a virtual address capability that is much larger. Basically, the 
80286 can access a collection of roughly 16,384 linear subspaces or segments each 
with a maximum size of 64 KB. This translates to a virtual memory size of 2°° 
bytes or 1 gigabyte (GB). The virtual memory allocation must map to physical 
memory for actual operation, using extended storage where needed. The notion of 
segmentation as described here allows programs to execute faster and requires less 
space, than does nonsegmented bulk linear addressing. 
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How does this protected virtual address mode manage memory? The segment 
selector is used. A particular segment is uniquely referenced by its selector, a 16-bit 
address with the following form: 


ee Es 


Index Tl RPL 


Here TI is the table indicator, which references a global space when set or a local 
space when zero. The global address space is used for systemwide data and code. 
The local address space is for general code and data applications such as user tasks. 
The first two selector bits are the requested privilege level (RPL) bits and relate to 
protection. This leaves 13 bits, which when coupled with the TI bit allow a segment 
address space of 2'* segments, as discussed above. We will see the impact of pro- 
tection shortly, but it will be useful, briefly, to explore these segment descriptors 
further. Note that the descriptor table registers point to tables that provide a com- 
plete description of the global address space (GDTR), one or more local address 
spaces defined dynamically by the LDTR, and an interrupt address space (IDTR). 

Within a descriptor table two main classes are recognized: segment descriptors 
and special-purpose control descriptors. Figure 1.4 illustrates a descriptor. They pro- 
vide the physical memory base address, segment size, transfer data, and access data. 
The special-purpose control descriptor is very similar. There is a global and several 
local descriptor tables as alluded to earlier. (It is these tables that are pointed to 
using the GDTR and LDTR.) 


ACCESS RIGHTS BYTE 
7 07 0 


BASE (15-0) 


ACCESS RIGHTS BYTE 


P = Present 

DPL_ = Descriptor Privilege Level 
Ss = Segment Descriptor 
TYPE = Segment Type 


A __ = Accessed Figure 1.4 80286 segment descriptor. 
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The 16-bit selector is mapped to a descriptor table entry with its subsequent 
24-bit base address. The TI bit determines whether the GDT or a LDT is to be se- 
lected. The INDEX field specifies the particular descriptor entry within the chosen 
table. To get this descriptor entry the processor simply multiplies the index value by 
8 in hardware and adds the result to the descriptor table base address. 

The segment address translation registers can be depicted as follows: 


Visible 48-Bit Hidden Descriptor Cache 


63 48 47 40 39 16 15 0 


16-bit Access | Segment base Segment size 
selector rights address 


Here the last 16 bits (bits 48-63) comprise the CS, DS, SS, or ES register values. 
These bits are the visible portion of the translation register. By loading a segment 
selector into one of these registers, the program makes the associated segment one 
of its four currently addressable segments. Note that the definition of the segment 
base address, the physical address associated with the 16-bit segment selector, must 
be correlated with the selector by the system software. It is this correspondence 
between the 16-bit selector and the segment base address that permits virtual ad- 
dressing to function properly. Both of these addresses, along with the access rights 
byte and segment size (the translation register contents), permit the correct mapping 
of virtual memory to physical memory by OS/2, for example. It is here, then, that 
the algorithms developed in the systems software effect the actual mapping of 
memory, and the content of this segment address translation register serves as the 
basis for this mapping. 

Figure 1.5 illustrates the protection levels permitted by the 80286 RPL selec- 
tion. The two bits provide for four levels of protection. In this figure level 0 is the 
most trusted and level 3 the least. Privilege level is a protection attribute assigned 
to all segments. Privilege checks are made automatically by the CPU hardware. Pro- 
grams at level 0 may access data at all other levels, while programs at levels 1-3 
may access data only at the same or a less trusted level. 

How does OS/2 make use of these levels? Typically, software at level 0 in- 
cludes services such as memory management, task isolation, intertask communica- 
tions, and I/O resource control. Level 1 is designated system services and provides 
functions such as file access scheduling, character I/O, and data communications. 
Level 2 corresponds to reserved space for customized applications such as database 
managers, spreadsheets, and word processors, as well as background tasks. Finally, 
level 3 contains general-purpose user application of the sort written about in the ex- 
amples in this book. Privilege applies to tasks and affects three different categories 
of descriptors: 
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1. Main memory segments 
2. Gates (used to change code segments) 
3. Task state segments 


APPLICATIONS 


EXTENSIONS 


SYSTEM 
SERVICES 


Figure 1.5 Protection-level software 
allocation and priority, based on level 
hierarchy, for the Intel 80286. 


Descriptor privilege is assigned when the descriptor is created. We have seen, for 
example, how segment descriptors are formed with their access rights byte and RPL 
bits controlling protection. 

Three kinds of control transfers can occur within a task: 


1. Intrasegment transfers 
2. Intersegment transfers at the same privilege level 
3. Intersegment transfers to different privilege levels 


The interlevel transfers must check for access permission and must ensure that a 
correct entry address is used. To achieve these control transfers, the gates indicated 
earlier must be used. 

A gate is a four-word control descriptor used to redirect a control transfer to 
a different code segment in the same or a more privileged level or to a different 
task. There are four types of gates: call gates, task gates, interrupt gates, and trap 
gates. All four gates define a new destination selector (16-bit), and offset (16-bit), 
which specifies the physical address to which the transfer is to take place. Call gate 
descriptors are established for call and jump instructions in the same manner as a 
code segment descriptor. Task gates specify intertask transfers for the initialization 
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and establishment of child tasks, information exchange, and synchronization. Inter- 
rupt gates permit system-level access of low-level hardware-driven interrupt services, 
and trap gates transfer control to system exception-handling services. 

Finally, task state segments are a special control segment defined uniquely for 
each task. They include the definition of the task address space and execution state. 
This segment has a special descriptor whose selector is contained in the Task 
Register. Each task state segment contains 22 words, including the current general- 
purpose register values and the SS and SP values for each current protection-level 
stack (there are four such stacks). The descriptor contains the task descriptor privi- 
lege level and the usual segment base and limit values. Hence protection mecha- 
nisms are extended to intertask control transfers using task state segment descriptors. 
Task switching is accomplished by loading the Task Register with the new task 
selector, marking the new task’s descriptor type as busy, and setting the Task 
Switched bit in the Machine Status Word (MSW). This MSW bit signals that the 
context of the processor extension (80287, for example) may not belong to the 
current task. 

So far we have looked at the 80286 hardware for Protected Mode operational 
features. These hardware features allow system software such as OS/2 to develop 
strong protection mechanisms in multitasking environments. Without this protection 
implementation of the software would necessarily be much more difficult to develop 
and software protection mechanisms would be required rather than a reliance on 
register bit monitoring. The room for error in such systems software becomes sub- 
stantially greater as application complexity increases. 


1.1.3 Software Operation for Protected Mode 
The flag word for the 80286 is 


UES SY CULES ER EAU ES EOLA TEER ES 


IOPL OF DF TF SF ZF 
where 
CF Carry Flag (set on high-order bit carry or borrow) 
PF Parity Flag (set if low-order byte contains an even number of 1’s) 
AF Auxiliary Flag (set on carry or borrow to low-order nibble) 
ZF Zero Flag (set if result 0) 
SF Sign Flag (0 if positive or 1 if negative: high-order bit of result) 
TF Trap Flag (single-step mode) 


IF Interrupt Flag (causes CPU to transfer control to a vector location) 
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DF Direction Flag (causes string instructions to auto-decrement when 
set) 

OF Overflow Flag (set if result is too large) 

NT Nested Task Flag (when set causes a return to the calling task for 
IRET) 


IOPL IO Privilege Level (specifies current task privilege level) 
The Machine Status World (MSW) has the following format: 


a snceacxemnatnpcsiereeanassnnentanketa ice 
Used by 80386 TS EM MP PE 


where 


PE Protected Enable (places 80286 into protected mode) 
MP Monitor Processor (allows WAIT states to be introduced for the 


80287) 
EM Emulate Processor (allows the 80287 to be emulated) 
TS Task Switched (allows test to determine if 80287 context belongs to 


current task) 


It is clear that modifications to the flag word (IOPL and NT) permit added 
software checking for Protected Mode status based on hardware. The MSW provides 
a software mechanism for checking coprocessor status with regard to the current 
80286 program context. In addition to these changes, a number of instructions have 
been added to the basic Real Address Mode set which reflect privileged and trusted 
operation. Instructions such as the following fall in this category of enhanced soft- 
ware instruction capability to support Protected Mode. 

SMSW Store MSW 

LIDT Load interrupt descriptor table register 

LMSW Load MSW 

CLTS Clear task switch flag 

LGDT Load global descriptor table register 

LLDT Load local descriptor table register 

LTR Load task register 

SGDT Store global descriptor table register 

SLDT Store local descriptor table register 

SIDT Store interrupt descriptor table register 
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These instructions are generally available only to system software. Once an operat- 
ing system is established (such as OS/2) for the system, privilege-level access must 
be regulated within the constraints of this system. The user, for example, cannot 
arbitrarily insert code at privilege level 0. During software implementation under 
OS/2, privilege-level access is regulated by the OS/2 system software and API serv- 
ice calls for normal application development. This sort of application development 
is the type treated in this book. 


1.2 A BRIEF LOOK AT OPERATING SYSTEM/2 


Figure 1.6 presents a simplified OS/2 architecture. This figure reflects the component 
parts needed to define operating systems software completely [18—21] and illustrates 
both the multitasking and memory management functions. As with most architec- 
tures, Figure 1.6 is a mix between static entities, such as loaders, and dynamic 
activities, such as intertask communications. The intent of the figure is to portray 
hierarchical relationships [22-25] for OS/2. 

Before we examine the major individual features of the IBM OS/2 implemen- 
tation, it will be useful briefly to discuss Figure 1.6. This architecture attaches equal 
importance to the 80286 (or 80386) hardware protection implementation and OS/2 
itself. Without the hardware mechanisms OS/2 would be a much bulkier and more 
sluggish operating system. Hence the Intel chip architecture deserves a substantial 
amount of credit for yielding an optimized multitasking executive. The dominant 
mechanism for installing multitask protection is the definition of privilege based on 
hardware monitoring and checking. This mechanism is put in place in the software 
during system initialization. The loader and kernel act at level 0 to define the 
baseline operating system. Device service is handled through the device drivers, 
which consist of three parts: 


1. An initialization routine 
2. A strategy routine 
3. An interrupt routine 


The initialization routine initializes the device by setting the device registers with 
proper data to establish mode of operation, and this routine also establishes any data 
structures (buffers and parameter data) needed by the device during operation. The 
strategy routine receives I/O requests from the kernel and initiates I/O. The Interrupt 
Service Routine (ISR) is the only OS/2 program privileged to accept and process 
hardware interrupts (signals on IRO-IR7 of the two 8259A PICs in the IBM PC AT, 
for example). The device service routines call DevHIp functions in order that the 
ISR can access application buffers from the kernel. I/O Protection Level checking is 
continuously monitored to validate what buffers may be accessed by the drivers. 
Other API functions are used to ensure proper physical memory segmentation, for 
example, as is the case with screen buffer access. 
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Figure 1.6 IBM OS/2 architecture. 
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The OS/2 executive is the main processing element of the architecture. This 
routine contains the core loop, which is the infinite loop sequence representing the 
idle system state and which may only be affected by a hardware interrupt such as 
the striking of a key on the keyboard. The executive has four components: file 
system management, data management, task management, and data segment defini- 
tion. All objects in the system represent named entities and are subject to file 
management rules. File permission and protection validation is conducted at a rela- 
tively high level in software. At a lower level, the protected address allocation 
requires privilege-level authority. 

Data management is an extension of file system management. This component 
of the executive ensures that segmentation violations do not occur because proper 
allocation is implemented. It manages extended files (disk and diskette files, for 
example). It handles the movement of data in a virtual memory context where the 
amount of virtual memory required for data, for example, can exceed the total 
available physical memory in the system. (This is also true for other memory types, 
such as program memory.) Segment sharing among tasks and other interprocess 
communication activities involving the access of data segments are managed by this 
component. 

The task manager is the primary dynamic activity element during program 
execution. We use the terms thread and process assuming some familiarity with 
these abstract concepts. Briefly, a thread provides program instructions and data in 
an execution environment that consists of registers, stacks, and CPU dynamics. 
Threads do not have system resources allocated to them, but may call or access such 
resources under the umbrella of a process. Here a process is a collection of threads 
and system resources allocated to a program. OS/2 task management includes sched- 
uling with a preemptive time-slicing dispatcher. This type of dispatcher is operated 
on a polling model concept where each thread has a fixed period of time during 
which it may execute (the time slice) before control is taken away (preempted) and 
the next thread rolled in and allowed to execute. The process continues in wrap- 
around fashion, and each time slice executes for an approximately equal length of 
time (at a given privilege level), which is dynamically allocated based on the 
number of threads active in the system. Task initialization is established by the task 
manager at level 0 and involves service calls of the type DosCreateThread or 
DosExecPgm. . 

Intertask communications typically involve semaphores, pipes, and queues. 
Also, shared memory segments can be used to pass data among threads and pro- 
cesses. A semaphore is a data structure that OS/2 passes to only one thread at a 
time. This provides for a rudimentary serialization when two threads, for example, 
need to access a common data area. OS/2 implements two kinds of semaphores: sys- 
tem and RAM semaphores. System semaphores are used for communication between 
processes and are implemented by DosCreateSem, for example. RAM semaphores, 
on the other hand, are used between threads in a single process. 

Pipes are buffer areas created by DosMakePipe and are accessed using pipe 
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read and write handles in much the same fashion that conventional file handles are 
used to access files. To use a pipe to communicate with another process, the pipe is 
first created and then one of its two handles (read or write) is passed to the second 
process using a common data structure. In accessing buffers via pipes the data is 
treated as a continuous stream. An alternative interprocess communications tool is 
the queue generated by the DosCreateQueue service. Here the data is viewed as an 
individual collection of finite-length elements that may be separately addressed or 
accessed. The major feature of the queue is the variability with which data elements 
may be accessed. 

Termination of a communication or task is typically initiated by API calls of 
the type DosCloseQueue, DosCloseSem, or DosExit. Finally, the task manager is 
responsible for maintaining all thread parameters on the local thread stack during 
roll-out by the dispatcher. When a task has been preempted it must maintain point- 
ers to entry points in the code and associated data segments that reflect its current 
execution position. This is what the task state segment contains, and the task 
manager is responsible for establishing and maintaining this segment. Data segments 
must, of course, be defined at the proper privilege level and accessed only with the 
proper privilege authority. This is also a function of the OS/2 executive. 

The user interface represents OS/2s interaction with the outside world. Two 
visual displays are possible: the VIO or full-screen command mode and the Presen- 
tation Manager (PM), a windowed mode where visual data from multiple tasks can 
be presented. The VIO has a familiar DOS-like screen. The PM is a dynamic dis- 
play environment capable of simultaneously illustrating multiple program execution 
through overlapping windows of the type found in the Microsoft Windows program 
and similar to the Apple MacIntosh display. The PM coordinates activity internally 
by exchanging messages among tasks and the PM executive. A preferred interface 
technique is the mouse, which moves a cursor around the screen. When the cursor 
is placed on a system or menu operation and the mouse single- or double-clicked, 
the command is executed. This requires an extensive command interpreter based on 
messages returned to the PM executive. 


1.2.1 Protected Mode 


In the discussion so far we have alluded to the API service routines. These are the 
topics of the next section, but it must be emphasized that they are a consequence of 
the Protected Mode implementation. Before examining the API, however, it is useful 
to look briefly at some of the Protected Mode operational considerations. 

When Real Address Mode is initialized and executes, the boot record causes 
the code segment register eventually to load with FOOO and the instruction pointer 
to load with FFFO. This address points to a private memory segment that provides 
64K bytes of code space for initialization code without changing CS. During initiali- 
zation of Protected Mode, several registers must also be initialized: Both the GDT 
and IDT base registers must point to a valid global descriptor table and interrupt 
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descriptor table, respectively. The 80286 next executes the LMSW instruction to set 
the protected enable (PE) bit and must follow this with an intrasegment JMP 
(unconditional jump) instruction to clear its CPU instruction queue of instructions 
decoded in Real Address Mode. To initialize the 80286 registers for the initial 
Protected Mode state the JMP instruction executes with a selector referring to the 
initial task state segment address used in the system. This loads the task register, 
LDTR, segment registers, and remaining general registers with the initial Protected 
Mode parameter data. The TR should point at a valid task state segment. 

We have seen a general description of Protected Mode features. The 80286 
mechanisms to protect critical instructions (that affect CPU execution states such as 
HLT, halt) have three attributes: 


1. They involve restricted usage of segments, with the only segments available 
for use by applications defined by the LDT and GDT. 


2. They involve restricted access to segments via privilege. 


3. They include privileged instructions or operations that may be executed only 
at privilege levels determined by the current privilege level and I/O Privilege 
Level (IOPL). 


These mechanisms yield checks that are performed for all instructions and include 
segment load checks, operand reference checks, and privileged instruction checks. 
Operand reference errors would include writes to the code segment or segment limit 
exceeded, for example. Finally, an example of a privileged instruction exception or 
error would be the execution of an IN or OUT (port input or output instruction, 
respectively) instruction when the current protection level for the executing task is 
less trusted than the required IOPL. 

Four types of control transfer can occur when a selector is loaded into CS: 
intersegment with the same privilege level, intersegment to the same or higher-privi- 
lege-level interrupt, intersegment to a lower privilege level, and a task switch. We 
have already briefly considered these transfers, but what are the privilege rules 
associated with these transfers? The rules are as follows: 


1. JMP or CALL direct to a code segment can only be to a segment with de- 
scriptor privilege level greater than or equal in privilege to the current privi- 
lege level. 


2. Interrupts within a task or calls that may change privilege levels can only 
transfer control through a gate at the same or a less privileged level (than the 
current privilege level) to a code segment at the same or more privileged level 
(than the current privilege level). 


3. Return instructions that do not switch tasks can only return to a code segment 
with the same or less trust. 


4. A task switch can be performed by a call, jump, or interrupt that references a 
task gate or task state segment of the same or less trust. 
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Any violation of these descriptor privilege-level rules will result in exception 13, 
indicating a segmentation violation. 

A task has a current privilege level (CPL) defined by the lower two bits of the 
CS register (in the selector), as we have seen. CPL can change only when CS 
changes, using a control transfer through gate descriptors to a new code segment. 
Tasks begin executing at the CPL specified by the task switch’s resulting code 
segment. Tasks executing at level 0 can access all data segments defined in both the 
GDT and the task’s LDT. Any control transfer that changes CPL within a task 
requires a change of stacks. Initial values of SS and SP for privilege levels 0, 1, and 
2 are maintained in the task state segment. The values for level 3 are de- 
fined by the application and affect such transfers as establishing a new thread using 
DosCreateThread. 

These brief remarks about the Protected Mode are intended to put the hard- 
ware implementation in perspective. We have seen how privilege-level monitoring, 
for example, serves as a basis for segment access during execution. The 80286 
hardware features include rules and rule checking to maintain privilege integrity, and 
this preserves proper task operation in a multitasking environment. 

Generally speaking, data such as the GDT, initial task state segment, and 
system services will be located in erasable programmable read-only memory as part 
of the system build. These are all loaded during the bootstrap process and precede 
the actual OS/2 executive load and initialization. The foregoing discussion presents 
the salient 80286 features applicable to a consideration of how OS/2 avoids segment 
violations. This is the cornerstone for multitasking and memory management. The 
80286 Protected Mode attributes are summarized briefly in Table 1.1. 


1.2.2 API Services 


The Application Program Interface services have been mentioned a number of times 
so far in the discussion, and Table 1.2 lists these functions (for Version 1.0), indi- 
cating whether or not they are conventional API (all the OS/2 services comprise the 
API, or a subset of the API, the DOS family API, which corresponds roughly to the 
BIOS and DOS services and runs under the DOS compatibility box as well as the 
Protected Mode). 

The API services are based on the CALL instruction rather than the INT 
instruction. These API functions act in similar fashion to conventional higher-level- 
language (HLL) routines with their individual stacks and local parameter spaces. For 
OS/2 programs written in assembly language, the API service request can be cum- 
bersome. On the other hand, these CS/2 service implementations add an elegance to 
the resulting code that with just a few exceptions enhances modular development. In 
a higher-level-language context the API services improve modularity and structure. 
We will see examples of the use of these services in an assembly language and C 
context throughout the remainder of this book. Basically, however, the API is most 
desirable in a HLL environment. 
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TABLE 1.1 80286 PROTECTED MODE FEATURES 
Feature Discussion 


I/O protection © To help manage I/O activities such as setting/clearing interrupts 
and port read/writes, the 80286 implements an I/O Protection 
Level (IOPL). This flag defines the minimum protection level 
at which a program must execute to perform I/O. This 
provides operating system control of the hardware. 

Privilege levels The 80286 provides for four levels of protection: 

1. PLO (Privilege 0): Most trusted; can access data at levels 
0, 1, 2, and 3. 

2. PL1 (Privilege 1): Can access data at levels 1, 2, and 3. 

3. PL2 (Privilege 2): Can access data at levels 2 and 3. 

4. PL3 (Privilege 3): Least trusted; can access data at 3. 

Address protection Through use of LDTs each application program is allocated a 
private memory space. No other tasks are allowed to enter or 
use a given task's LDT area. Any common memory elements 
must be shared using the GDT. 

Memory attributes § These attributes are specified in the descriptor table access byte. 
They include such features as read/write access and descriptor 
privilege level as well as a flag to indicate execution only 
(versus addresses associated with variable allocation). 


TABLE 1.2 APPLICATION PROGRAMMING INTERFACE ROUTINES 


Name API FAPI Description 
Tasking 

DosCreateThread X Creates asynchronous thread 

DosCWait X Places current thread in wait state 

DosEnterCritSec X Disables thread switching 

DosExecPgm x Allows another program to 
execute a child 

DosExit x Issued at completion of execution 

DosExitCritSec X Reenables thread switching 

DosExitList Xx Maintains an exit list for routines 

DosGetInfoSeg x Returns the address of a data 
segment 

DosGetPrty X Gets the priority of the current 
thread 

DosKillProcess X Terminates a process 

DosPtrace X Interfaces to kernel for debugging 

DosSetPrty X Changes priority of child process 


Asynchronous Notification 
DosHoldSignal X Changes signal processing 
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TABLE 1.2 (Continued) 


Name 


DosSetSigHandler 


Interprocess Communication 


DosCloseQueue 
DosCloseSem 
DosCreateQueue 
DosCreateSem 
DosFlagProcess 


DosMakePipe 
DosMaxSem Wait 
DosOpenQueue 
DosOpenSem 
DosPeekQueue 
DosPurgeQueue 
DosQuery Queue 
DosReadQueue 
DosResumeThread 
DosSemClear 
DosSemRequest 
DosSemSet 
DosSemSetWait 
DosSem Wait 
DosSuspendThread 


DosWriteQueue 


Timer 


DosGetDateTime 
DosSetDateTime 
DosSleep 


Memory Management 


DosAllocSeg 
DosAllocShrSeg 
DosAllocHuge 


DosCreateCSAlias 
DosFreeSeg 
DosGetHugeShift 


API 


x KX KK XK 


x KK KK KKM KK KKK KK 


x< 
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Description 


Notifies OS/2 of a handler for a 
signal 


Closes a queue 
Closes a semaphore 
Creates a queue 
Creates a semaphore 


Allows a process to set an 
“event” flag 


Creates a pipe 

Blocks until semaphore clears 
Opens queue 

Opens semaphore 

Examines element in queue 
Purges a queue 

Finds the size of a queue 
Reads an element from a queue 
Restarts a thread 

Clears a semaphore 

Obtains a semaphore 

Sets a semaphore 

Blocks a thread until a semaphore 
Waits for a semaphore to clear 


Temporarily suspends thread 
execution 


Adds an element to a queue 


Gets the current date/time 
Sets the date/time 
Suspends the current thread 


Allocates a segment of memory 
Allocates a shared segment 


Allocates multiple memory 
segments 


Creates a code segment descriptor 
Reallocates a memory segment 


Returns a shift count for deriving 
selectors 
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TABLE 1.2 (Continued) 


Name 


DosGetShrSeg 
DosGetSeg 
DosGiveSeg 


DosLockSeg 
DosMemAvail 
DosReallocHuge 
DosReallocSeg 
DosSubAlloc 


DosSubFree 


DosSubSet 
DosUnlockSeg 


Dynamic Linking 
DosFreeModule 


DosGetModHandle 


DosGetModName 


DosGetProcAddr 
DosLoadModule 


DosGetMachineMode 


BadDynLink 


Device Monitors 
DosMonClose 


DosMonOpen 
DosMonRead 
DosMonReg 

DosMonWrite 


Session Management 


DosStartSession 
DosStopSession 
DosSelectSession 


DosSetSession 


API 


x< 


x Kx K 


FAPI 


x 
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Description 


Accesses shared memory 

Accesses shared memory 

Yields shared access to another 
process 

Locks a discardable segment 

Returns size of largest free block 

Changes huge memory size 

Changes segment size 

Allocates from a previous 
allocated segment 

Frees from a previous allocated 
memory 

Initializes a segment 

Unlocks a discardable segment 


Frees a dynamic link module 

Returns handle for dynamic link 
module 

Returns pathname for dynamic 
link module 

Returns FAR procedure address 

Loads a dynamic link module 

Returns current CPU mode 

Error on dynamic link 


Terminates character device 
monitoring 

Accesses a character device 

Moves data 

Establishes I/O buffer 

Writes to the monitor's buffer 


Starts a session 

Stops a session 

Allows a parent to switch to a 
child 


Sets child session status 
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TABLE 1.2 


Name 


Device I/O Services 


DosBeep 
DosCLIAccess 


DosDevConfig 
DosDevIOCtL 


DosGetPID 
DosPFSActivate 


DosPFSCloseUser 
DosPFSInit 


DosPFSQueryAct 
DosPFSVerifyFont 


DosPhysicalDisk 
DosPortAccess 


DosSendSignal 


KbdDeRegister 
KbdCharIn 
KbdClose 
KbdFlushBuffer 
KbdFreeFocus 


KbdGetCp 
KbdGetFocus 


KbdGetStatus 
KbdOpen 
KbdPeek 


KbdRegister 
KbdSetCp 
KbdSetCustXxt 


(Continued) 
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Description 


Beeps speaker 

Requests privilege for enabling/ 
disabling interrupts 

Gets information about attached 
devices 

Sets up control functions for a 
specified device 

Returns current process ID 


Specifies the code page and foot 
to make active 


Indicates the spool file is closed 


Allows initialization of the code 
page and font 


Queries the active code page and 
font 


Indicates validity for the 
specified code page and font 

Obtains disk information 

Requests or releases port I/O 
privilege 

Sends a Ctl/c or Ctl-Break to 
process 

Deregisters a keyboard 

Reads a character 

Ends the existing logical keyboard 

Clears the keyboard buffer 


Frees the logical to physical 
keyboard bond 


Allows access to the current 
code page 

Binds the logical to physical 
keyboard 

Gets the state of the keyboard 

Creates a new logical keyboard 


Returns the last character without 
clearing the keyboard buffer 


Registers a keyboard 
Sets the code page 


Installs a code page and calling 
handle 
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TABLE 1.2 (Continued) 


Name API FAPI Description 


KbdSetFgnd 


Raises the priority of the 
foreground keyboard’s thread 


KbdSetStatus Sets the keyboard characteristics 
KbdStringIn Reads a character string 
KbdSynch X Synchronizes access for a 
keyboard to device driver 
KbdXlate 4 Translates scan codes to ASCII 
MouClose Xx Closes the mouse driver 
MouDeRegister 4 Deregisters a mouse device 
MouDrawPtr x Opens a mouse pointer image to 
the mouse 
MouFlushQue 4 Empties the mouse queue 
MouGetDevStatus 4 Returns status flags for the mouse 
driver 
MouGetEventMask X Returns event mask for mouse 
MouGetNumButtons X Returns number mouse buttons 
Supported 
MouGetNumMickeys x Returns number of mouse 
movement units per centimeter 
MouGetNumQueEl Xx Returns status for mouse device 
drive event queue 
MouGetPtrPos Xx Gets row and column position of 
mouse 
MouGetPtrShape x Gets the pointer shape 
MouGetScaleFact X Gets the scaling factors for the 
mouse 
MoulnitReal X Initializes the DOS mode mouse 
MouOpen X Opens the mouse device 
MouReadEventQue X Reads an event from the mouse 
device event queue 
MouRegister X Registers a mouse 
MouRemoves Ptr X Clears a pointer area from mouse 
use 
MouSetDevsStatus X Sets mouse status 
MouSetEventMask X Assigns a new event mask 
MouSetPtrPos X Resets the row and column 
position for the mouse 
MouSetPtrShape X Sets the mouse shape 
MouSetScaleFact X Assigns the mouse a new pair of 
| scaling factors 
MouSynch X Synchronizes the mouse 
VioDeRegister X Deregisters a video subsystem 
VioEndPopUp X Closes a temporary screen 
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TABLE 1.2 (Continued) 


Name 


VioGetAnsi 
VioGetBuf 


VioGetCp 
VioGetConfig 
VioGetCurPos 
VioGetCurType 


VioGetFont 
VioGetMode 


VioGetPhysBuf 


VioGetState 
VioModeUndo 
VioModeWait 


VioPopUp 
VioPrtSc 
VioPrtScToggle 
VioReadCellStr 


VioReadCharStr 


VioRegister 


VioSaveRedraw Undo 
VioSavRedraw Wait 


VioScrLock 
VioScrollDn 
VioScrollUp 
VioScrollLf 
VioScroliRt 
VioScrUnLock 
VioSetAnsi 


VioSetCp 
VioSetCurPos 
VioSetCurType 
VioSetFont 
VioSetMode 
VioSetState 


API 


FAPI 
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Description 


Returns the current ANSI 
ON/OFF state 

Returns the address of the logical 
video buffer 


Allows a query of the code page 
Returns the display configuration 
Returns the cursor position 
Returns the cursor type 


Returns font 
Returns display mode 


Gets addressability to physical 
display buffer 


Gets display state 
Changes mode 


Allows notification when display 
must be restored 


Allocates a temporary screen 
Copies the screen to printer 
Called when Ctrd-PrtSc is entered 


Reads character-attribute pairs 
(cells) from screen 

Reads a character string from the 
display 

Registers an Alternate Video 
subsystem 

Cancels a VioSavRedrawWait 


Notifies a redraw must be 
performed 


Locks the physical display 
Scrolls down 

Scrolls up 

Scrolls left 

Scrolls right 

Unlocks the physical display 


Activates or deactivates ANSI 
support 


Sets the code page 

Sets the cursor position 
Sets the cursor type 
Downloads a display font 
Sets display mode 

Sets the display state 
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TABLE 1.2 


Name 


VioShowBuf 
VioWrtCellStr 


VioWrtCharStr 


VioWrtCharStrAtt 


VioWrtNAtt 
VioWrtNCell 
VioWrtNChar 


VioWrtT TY 


File 1/O 


DosBufReset 


DosChDir 
DosChgFilePtr 
DosClose 
DosDelete 
DosDupHandle 


DosFileLocks 


DosFindClose 


DosFindFirst 
DosFindNext 


DosMkDir 
DosMove 
DosNewSize 
DosOpen 
DosQCurDir 


DosQCurDisk 


DosQFHandState 


(Continued) 
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Description 


Updates the physical display with 
the logical 

Writes a string of character- 
attribute cells to display 

Writes a character string to the 
display 

Writes a repeated attribute string 
to the display 

Writes an attribute M times to 
the display 

Writes a cell M times to the 
display 

Writes a character M times to 
the display 

Writes a character string to the 
display 


Flushes a requesting process 
cache buffer 


Defines the current directory 

Moves the read/write pointer 

Closes a file handle 

Removes a directory entry 

Returns a new file handle for an 
open file 

Locks and unlocks a range in an 
open file 

Closes the association between 


directory handles and search 
functions 


Finds the first set of names that 
match a directory specification 


Locates the next set of matching 
directory entries 


Creates specifies directory 
Moves a file 

Changes a file size 

Opens a file 


Gets full path name for current 
directory 


Gets the current default drive 


Queries the state of the specified 
files 
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TABLE 1.2 


Name 
DosQFileInfo 
DosQFsInfo 
DosQHandType 
DosQVerify 


DosRead 
DosReadAsync 


DosRunDir 
DosScanEnv 


DosSearchPath 
DosSelectDisk 
DosSetFHandState 
DosSetFileInfo 
DosSetFileMode 
DosSetFsInfo 


DosSetMaxFH 


DosSetVerify 
DosWrite 
DosWriteAsync 


Errors and Exceptions 


DosErrClass 
DosError 


DosSetVac 


Messages 


DosGetMessage 


DosInsMessage 
DosPutMessage 


Trace/Program Startup 


DosGetEnv 


(Continued) 
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Description 


Returns information for a specific 
file 

Queries information from a file 
system device 


Determines whether a handle 
references file/device 

Returns the value of the verify 
flag 

Reads from a file to a buffer 


Transfers from a file to a buffer, 
asynchronously 


Removes a subdirectory 


Searches an environment for a 
value 
Searches a path for a filename 


Specifies the default drive 
Sets the state of a file 
Specifies information for a file 
Changes the attributes of a file 


Specifies information for a file 
system device 


Defines a maximum number of 
file handles 


Sets a verify switch 
Transfers from a buffer to a file 


Transfers from a buffer to a file, 
asynchronously 


Returns error code options 


Allows the disabling or user 
notification on errors 


Allows address registration for 
machine exceptions 


Retrieves a message from a 
message file 


Inserts text into message body 
Outputs a message | 


Returns a pointer to the 
environment string 
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TABLE 1.2 (Concluded) 


Name API FAPI Description 


DosGetVersion X Returns the OS/2 version number 


Code Page Support 


DosGetCp X Gets the current code page 
DosSetCp X Sets the current code page 
DosSetProcCp X Sets the current code page 


Country Support 


DosCaseMap X Case maps country codes to a 
binary string 

DosGetCollate X Obtains country information 

DosGetCtryInfo X Obtains country information 

DosGetDBCSEv X Obtains country environment 
vector 


Most microcomputer system software involves intersegment references between 
segments contained in the program file obtained from the linker, the .EXE file in 
DOS. This reference mechanism is referred to as static linking because it is imple- 
mented prior to run-time loading. Loading merely brings the segments into mem- 
ory and modifies fix-up points to reflect the correct intersegment references. 

OS/2 allows the loader (not the linker) to reference segments included in spe- 
cial dynamic-link libraries (DLL). The entire APT is based on DLL programming. 
How does a dynamic-link reference function? Basically, any program can reference 
DLL routines by indicating that they are externally defined (using the EXTRN 
pseudo-op, for example, in an assembler program). At link time the system matches 
external references with other object modules (.OBJ files) and libraries (.LIB files) 
specified. Since the DLL routines are an .EXE file and suitable for run-time load- 
ing, they do not fall in the .OBJ or .LIB category. A new type of library file is 
required, the dynamic-link definition library file. This file simply satisfies the exter- 
nal reference by indicating to the loader the location of the DLL routine involved. 
At run time the loader then adds the DLL code from storage to the executable 
module. 

The API call interface employs dynamic linking. The major advantages to this 
approach are that: 


1. The API code can easily be modified at the system level 


2. The API call can be satisfied with in-line code instead of the DLL code if 
desired by proper loading 


3. The API can include some services not essential to kernel-level privilege, and 
these services can be implemented with less protection 


4. The API call is direct, not via vector table routing 
5. The API library can easily be expanded 
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In Chapter 2 we begin to develop the programming techniques needed to access 
properly the services outlined in Table 1.2. 


1.2.3 Memory Management 


OS/2 provides a significant memory management capability by using the hardware 
features of the 80286, together with its system architecture. OS/2 provides the capa- 
bility to move segments around and free memory in response to DLL requirements. 
Also, using the P bit of the descriptor, OS/2 can determine when a referenced 
segment is needed and dynamically roll these segments in or out of memory from 
extended storage, in response to program execution. Such segment swapping is the 
basis for allowing large-scale access to the virtual address space in a given physi- 
cal memory implementation. Provision exists to: 


1. Create or close new segments 
2. Create or close huge segments (greater than 64 KB) 
3. Suballocate segments 


This corresponds to the demand loading philosophy, which OS/2 supports, and 
allows dynamic reallocation and subdivision of memory in response to changing 
requirements. 


1.2.4 Multitasking 


Just as memory management has been addressed earlier in the chapter, multitasking 
has been covered in Sections 1.1 and 1.2.1. We have mentioned the notion of 
threads (a dispatchable unit), processes (a collection of threads and system re- 
sources), and a session is a collection of processes run in a virtual context. Under 
OS/2, for example, a given element of program code comprises a thread’s executable 
context. This may run as multiple instances in which multiple copies of the thread 
are executed as individual tasks, each task running the same code. Based on this 
interpretation the meaning of an instance is clear: an executing entity dynamically 
different from all others. 

The reentrant nature of OS/2 threads requires that if multiple threads access the 
same data block, the threads must synchronize access to this data. This synchroni- 
zation can be accomplished using a number of OS/2 features already discussed 
(semaphores, queues, pipes, flags, and shared memory). Interprocess communication 
requires the use of these facilities, and threads desiring to access such common data 
blocks must serialize their access. In general, when no common access between 
processes is required, OS/2 will asynchronously execute the processes in a multi- 
tasking situation. 

A simple example of process synchronization is presented in Chapter 2, where 
a common data area (shared segment) is established using DosAllocShrSeg and the 
first few bytes are used to establish a handshake. The creating process sets the flag 
byte to zero and turns on the child process, which also has access to the segment. 
Once the child process completes its generation of data (to be used by the parent), 
it sets the flag to 1. The parent, sensing a 1, then accesses the segment. 
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Semaphores, pipes, and queues have much the same functional behavior ex- 
cept that they represent tools specifically designed for interprocess exchanges. These 
OS/2 objects represent a formal extension of interprocess communications (compared 
with the shared memory flag above, for example). DosSetSigHandler and 
DosFlagProcess are examples of formal flag implementation services. We examine 
those resources in later chapters. 

Processes are created with the API service DosExecPgrm, as we shall see in 
Chapter 2. They are hierarchical in that the creating process serves as the parent, 
with the created process the child. The API DosKillProcess can be used to terminate 
a child process. At creation a process can be established asynchronously, during 
which the parent continues to execute in normal time-slice fashion, or synchro- 
nously, where the parent is suspended until the child completes execution. When a 
thread is created it assumes the priority level of its creator. Using DosSleep a thread 
may stop execution for a fixed period. During this period the thread is not allowed 
to access system resources. 

We have considered dynamic linking, in which a DLL is created and an asso- 
ciated definition file containing pointers to the DLL entries. At run time the defini- 
tion file has already been linked with the main calling routine, so the loader simply 
brings the DLL into memory and completes its entry-point fix up. A second type of 
dynamic linking exists called run-time dynamic linking. In the latter procedure the 
API DosLoadModule can actually be used to load a DLL after execution begins. 
The difference between run-time dynamic linking and load-time dynamic linking is 
that loading the DLLs and entry point fix-ups can occur after execution begins in 
the former if needed, whereas they must occur during loading in the latter. 

Finally, we look briefly at input and output (I/O) in the privileged multitask- 
ing environment. I/O occurs from level 2, whereas applications execute from 
level 3; hence OS/2 must build a call gate for access to segments that accomplish 
I/O— I/O-protected segments (IOPS). Such segments are created by the loader, and 
typically, API calls such as DosOpen or DosClose establish generation of an IOPS 
(see Table 1.2). 


1.2.5 Version 1.0 and 1.1 Differences 


Earlier we saw the API functions described (Table 1.2). In the IBM OS/2 Standard 
Edition 1.0 these functions comprised the bulk of the services afforded by OS/2 and 
were intended for use by programmers desiring to access these services. The Toolkit 
routines (reference 7) provide a collection of include files (for both C and assem- 
bler) that make use of the API services relatively easy. 

With the development of Standard Edition 1.1 (aside from some relatively 
minor enhancements) the addition of the Presentation Manager (PM) graphical inter- 
face, and its associated 300 plus function library, is the major improvement over 
Version 1.0. Essentially, OS/2 under Version 1.0 employs a DOS-like full-screen 
command mode for the user interface. This display mode is capable of addressing 
only one screen at a time. Under the PM a Windows-like interface is presented and 
each executing context can be visualized sunumtancously as part of a peda of 
windows occupying the screen. 
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It is programming of the OS/2 PM that constitutes the major enhancement of 
Version 1.1. This programming employs techniques similar to those outlined in the 
Windows Software Development Kit (SDK) [26-28] for development of Windows 
programs. 


1.3 THE OS/2 PRESENTATION MANAGER 


It is worthwhile to look briefly at the Presentation Manager (PM) to get a feeling for 
how this type of interface is implemented. The PM runs as an executive subset 
under OS/2. IBM has developed the Systems Application Architecture (SAA) and 
the PM implements the Common Programming Interface (CPI) component of SAA, 
which makes portability to other SAA-supported environments (such as VM and 
MVS on the System/370 and Operating System/400 on the Application System/400) 
relatively straightforward. 

Communications and network-intensive applications are not generally amenable 
to the SAA without additional software support. The Extended Edition Version 1.1, 
for example, is intended for these more uniquely hardware-specific applications. 
Examples include airline reservation systems, bank transaction processing, some 
large-scale process control applications, real-time processing, and communications 
front-end (physical layer) processing. 

The PM interacts with the OS/2 user via a graphical user interface [30-35]. By 
graphical user interface we mean the screen appearance when the PM is invoked. 
This display is illustrated in Figure 1.7 with a typical pulldown menu. The maxi- 
mize/minimize buttons can be used to reduce the contents of the client area to an 
icon. This icon can be restored using the mouse. The client area contains the visible 
portion of the display context, which presents the active window interface. It is here 
that the executing program displays its particular graphical context. The PM allows 


System Menu Icon 


Maximize/Minimize/ 


Action Bar Restore Buttons 


Vertical Scroll Bar 


Panel Body Area 


Horizontal Scroll Bar 


Figure 1.7 The Presentation Manager standard window. 
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the client area to be subdivided into tiled (windows adjacent to each other) or 
overlapped (windows lying on top of each other with varying offsets) windows. This 
facilitates a partial display of the contents of several windows simultaneously. 

In addition to the features illustrated in Figure 1.7, the programmer can call up 
modal and modaless dialog boxes and message boxes. These can be used to achieve 
I/O in the PM context. A modal dialog box retains control of the execution until it 
is destroyed (usually by clicking the mouse over a termination panel). A modaless 
dialog box allows the PM to permit windows in other applications to be activated 
after it has been created. A message box is a predefined dialog window available to 
all applications for displaying text and receiving user I/O. 

The PM has a strong graphics capability (as differentiated from graphical 
interface) with which computer-generated graphics may be displayed in the client 
area. This Graphics Program Interface (GPI) employs API calls beginning with Gpi. 
The PM also has a clipboard that can be used to hold intermediate data and re- 
sources (such as metafiles and bitmaps). A metafile defines the contents of a win- 
dowed picture so that it can be used by other applications. These metafiles are 
created using GPI calls and conform to the Mixed Object Document Content Archi- 
tecture (MODCA) interchange standard. A bitmap, on the other hand, is a represen- 
tation in memory of data displayed on an all-points-addressable basis and requires 
that the object in question be capable of being specified in this mode. 

Finally, the programming for the interface itself employs a number of new 
library elements. The PM executive is a dynamic program that is constantly access- 
ing each application context for changes and conversing with the application via a 
stream of messages. When an application executes various window functions, for 
example, the function causes specific messages to be sent to the PM executive. 
These are then interpreted and the executive generates a response. 

The general PM program flow of activity is illustrated in Figure 1.8, where 
termination of the window is accomplished by the executive in response to a 
WM_QUIT message. This flowchart shows the setup code as distinct from the 
message-processing loop, as it is. C is the language of choice for programming the 
PM executive. 

Conventional C programs have a rere template that appears as 


Preprocessor 
main( ) 


{ 

{ 
functionl() 
} 

} 


functionnNn( ) 


{ 
{ 
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Y 
INITIALIZE 
WINDOW 


NORMAL 
SETUP 
GET 
MESSAGE 
Ss 
TRANSLATE TERMINATE 
MESSAGE WINDOW 
SEND TO EXIT 
WINDOW 
PROCESS 
WINDOW Figure 1.8 Dynamic picture of a 


Windows application, similar to the PM 
implementation. 


Each function is callable internal to either main () or another (group of) function(s). 
A simple PM program with one window might have a template of the following 
form: | 
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Preprocessor 
void cdecl main(argc,argv) 
{ 
-code to initialize window 
-~loop to continuously read messages sent from the executive 
} 
“window function 
{ 
-this function directs execution to appropriate PM func- 
tions based on “message” input from the PM executive 


} 


“initialization functions” 


-functions needed to initialize the first, additional, and 
every instance of a window 


} 


other needed user-defined functions 


oe .° 


Figure 1.9 illustrates a Structure Chart for the upper hierarchical levels of a PM 
application. This chart is generic in the sense that it only indicates entities that are 
common to all PM programs. The reader familiar with the Microsoft Windows 
executive will see a close parallel between programming for this executive and 
programming the PM executive [29]. 
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PM 
APPLICATION 
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INITIALIZE 
WINDOW 


200 300 


PROCESS EXIT 
MESSAGE WINDOW 


110 120 210 


ESTABLISH CHECK FOR GET 
INSTANCE PREVIOUS MESSAGE 
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220 230 


TRANSLATE DISPATCH 
MESSAGE MESSAGE 


221 222 4231 232 
RECEIVE CONVERT TO PASS 


FORMATTED INTERNAL MESSAGE MESSAGE TO 


STRUCTURE WINDOW 
MESSAGE CODE SAGCEBURE 


Figure 1.9 Generic Structure Chart for the upper hierarchical levels of a 
Presentation Manager application. 
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1.4 SUMMARY 


In this chapter we have introduced the IBM Operating System/2 in the framework 
of the Intel 80286 and 80386 CPUs. Initially, the CPU registers were described and 
the Protected Mode address space examined. The Protected Mode provides a frame- 
work from which to perform memory management and multitasking because of the 
hardware interlocks into segment management. Basically, the access rights control 
byte in the segment address translation register word determines what data and con- 
trol segments will have access to a given memory location. 

This segment control, then, is the mechanism by which the hardware delimits 
Protected Mode access. This is applied to the software via the operating system (and 
the local descriptor tables (LDTs) and the global descriptor table (GDT)). OS/2 
provides system services similar to the BIOS and DOS interrupt services via the 
family Applications Programming Interface (FAPI). The FAPI is a subset of the 
more complete API functions, which represent a complete set of Protected Mode 
services. Representative of these services are the following categories 


1. Mouse (Mou) 

. Video (Vio) 

» DOS (Dos) 

. Graphical (Gpi) 
Spool (Spl) 
Device (Dev) 

» Keyboard (Kbd) 
. Window (Win) 


eI AM AWD 


The API calls, then, allow access to system hardware and file services under OS/2. 
OS/2 has provision to add devices to the system by creation of additional device 
drivers and input/output privilege level (IOPL) is assisted using the Dev and Dos 
Services. | 

The Presentation Manager (PM) represents the Version 1.1 user-friendly graph- 
ical interface for OS/2. Under Version 1.1 the user also has a choice of the full- 
screen command prompt interface mode which is that employed by Version 1.0. The 
PM display is similar to that used by Microsoft Windows Version 2.0 and provides 
for overlapped (or tiled) window presentation of active process information in a 
multitasking environment. The PM executive interacts dynamically with the execut- 
ing programs. Associated with the PM are a large class of functions (window func- 
tions) used to regulate the interface under program control. The messages exchanged 
between the PM executive and the program are continuous and dynamically varying. 
Hence this executive provides a time-varying interactive display that can be updated 
and controlled using the mouse. It is very similar to the interface provided by the 
Apple MacIntosh operating system. 
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PROBLEMS 


In Real Address Mode assume a CS register value of 07F8H and an IP register value 
of 274AH. What is the 20-bit physical address? 


Does the fact that OS/2 is a multitasking operating system imply that it is a multi- 
processor operating system, as well? 

What is the largest fixed-point value that the 80386 can accommodate? Largest signed 
fixed-point value? | 

The exit processing for OS/2 is via a call to DOSEXIT rather than a RET instruction. 
If the requisite processing for DOSEXIT is 


EXTRN DosExit:FAR 
PUSH WORD ActionCode ;Indicates end thread or process 


PUSH WORD ResultCode ;Result Code 
CALL DosExit 
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1.5 


1.6 


1.7 


1.8 


1.9 


1.10 


1.11 


1.12 


1.13 
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define a macro 
@DosExit action, result 


that can be used to setup and execute the exit operation. 


The video screen unlock processing for OS/2 is via a call to VIOSCRUNLOCK. As- 
suming that the requisite processing for this call is 


EXTRN VioScrUnLock: FAR 


PUSH WORD VioHandle ;Video handle 
CALL VioScrUnLock 


define a macro 
@VioScrUnLock viohdl 


that can be used to setup and execute the unlock operation. 


The video screen lock processing for OS/2 is via a call to VIOSCRLOCK. Assuming 
that the requisite processing for this call is 


EXTRN VioScrLock:FAR 

PUSH WORD WaitFlag ;Block or not 

PUSH BYTE Status ;Lock status returned (address) 
PUSH WORD VioHandle ;Video handle 

CALL VioScrLock 


where PUSH@ means to push an address on the stack, define a macro 
@VioScrLock waitf,iostat,viohdl 


that can be used to setup and execute the lock operation. 

What are the three principal features that the OS/2 Standard Edition contributes over 
conventional DOS operating system characteristics? 

While 80286 code (source) will run on 80386 systems, why will 80386 applications 
code generally not run on 80286 systems? 

In the IBM PC AT, 16 levels of hardware interrupts are available to the system user. 
How many 8259As are required to support this number of interrupt levels? 

The DOS partition in the IBM microcomputer environment supports the first 1 MB of 
addressable memory. Why do most early systems allow a maximum of only 640 KB 
of program memory access? Where does OS/2 extended memory reside? 

What is the difference between physical and virtual memory, and how is virtual 
memory managed? 

How does OS/2 differentiate system memory space from applications memory space? 
How much virtual memory space is accessible by applications? 

Why would data communications processing not reside at level 0 to ensure that no 
data is lost during a communications session? 
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1.14 
1.15 


1.16 
1.17 


1.18 


1.19 


1.20 


1.21 


How does the 80286 CPU know that the system is to operate in Protected Mode? 
When writing a device driver, mixed-language programming is probably an optimum 
approach. Assuming that a driver is written using a combination of C and assembly 
language, what parts are likely candidates for assembler code? What parts are likely 
candidates for C code? 

Explain the major difference between a pipe and a queue. 

Would you say that the API implementation represents a favorable step for assembly 
language programming of OS/2? For C programming of OS/2? Explain. 

If two threads from the same process need to access a common data area, will they 
run synchronously or asynchronously? If the threads are from different processes, will 
they access in synchronous or asynchronous fashion? 

What is the thread equivalent to DosKillProcess? How does it differ from the activity 
for a process? 

Can we use the Gpi services with full-screen command mode to generate screen 
graphics under CGA, for example? 

Which is preferred in a multitasking environment: modal or modaless dialog box 
implementation? 


PART Il 
Programming OS/2 Using Assembler 


2 Introductory OS$/2 
Assembler Programming 


OS/2 is a unique program environment devoid of the normal interrupt calls found in 
conventional assembly language programs. In their place OS/2 implements Applica- 
tion Program Interface (API) function calls, which provide the programmer with ac- 
cess to system services. Specific services include the familiar DOS BIOS and 
INT21H function calls, an enhanced set of video display handlers, mouse services, 
and keyboard handlers. These are the most obvious extensions of OS/2, and they 
permit the user a vastly increased capability to develop multitasking modules and 
extend program usage beyond the normal 64K segment limit. 

In this chapter we examine assembly language programming in the context of 
OS/2 [1,2]. The goal of the exposition is to provide the reader with examples of the 
usage of assembly language in the OS/2 framework. This is not a treatise on how to 
program assembler; rather, we hope to achieve an understanding of the OS/2 inter- 
face. 


2.1 OS/2 SERVICES: ACCESSING THE API 


A great deal of the new programming emphasis using OS/2 is the API services 
which are contained in the IBM (or Microsoft) supplied library, API.LIB. The serv- 
ices contained in API.LIB can be accessed through uppercase specification of the 
service name preceded by proper setup of parameter information appropriate to the 
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function in question. Unlike the DOS and BIOS interrupt routines, which pass 
parameter information using the general-purpose registers, the OS/2 API procedures 
receive parameters via the stack, which must be installed by the user. This is in 
much the same fashion as the passing of parameters to functions or subroutines in 
a higher-level language (HLL). 

To understand how this works consider the video API call, which returns the 
cursor position to two stack locations. This routine, VioGetCurPos, has the follow- 
ing calling sequence for the service [3]: 


1. Define VioGetCurPos as EXTRN and FAR 
2. PUSH a 32-bit address for 


row (word) 
column (word) 


on the stack, respectively 
3. PUSH a device handle 


VioHandle (word) 


on the stack 
4. CALL VioGetCurPos 


In this example the routine VioGetCurPos is treated in mixed upper and lower case 
for readability. The actual OS/2 library reference is upper case: 


VIOGETCURPOS 


To continue to use the more readable mixed-case references, which are in the style 
of the IBM references, the programmer must consider what is available or can be 
developed to facilitate the use of these mixed-case calls. Fortunately, IBM provides 
several include files (with extension .inc) for use with the assembler that set up 
macros for using the API library. This setup includes loading the stack with the 
proper parameters needed by the API service routine. OS/2 has two include files, 
doscalls.inc and subcalls.inc, that properly develop macros to be called for API 
service. These two files are loaded using a third file, sysmac.inc, which simply 
installs doscalls and subcalls as macro libraries: 


IFl 
include sysmac.inc 
ENDIF 


The file doscalls.inc contains macros for calling all the Dos...calls. The file 
subcalls.inc contains macros for calling all kbd..., Mou..., and Vio... calls. 
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Returning to VioGetCurPos, consider the subcalls macro used to set up and 


call this service routine: 


@vioGetCurPos macro row, column, handle 
@define VIOGETCURPOS 
@pushs row 
@pushs column 
@pushw handle 
call far ptr VIOGETCURPOS 
endm 


We see immediately that this macro calls three other macros: @define, @pushs, and 
@pushw. These macros are defined as follows: 


@define macro callname 
ifndef callname 
extrn callname:far 
endif 
endm 

@pushs macro parm 
-errb <parm> 
mov ax,SEG parm 
push ax 
lea ax, parm 
push ax 
endm 

@pushw macro parm 
MOv ax, parm 
push ax 
endm 


Clearly, @define is used to get VIOGETCURPOS as an externally defined 
FAR procedure (it appears in API.LIB). The macro @pushs pushes a 32-bit address 
for the dummy parameter, parm, onto the stack and @pushw pushes parm itself onto 
the stack. The calling sequence for @VioGetCurPos sets up row and column to 
receive the cursor position values after the final FAR call to VIOGETCURPOS. 

This is how the OS/2 API services are accessed using assembly language and 
the doscalls.inc, subcalls.inc, and sysmac.inc files. In this chapter we use only a 
small subset of the API calls. These services are indicated in Table 2.1. Generally, 
the focus of interest in this chapter is on the printer, keyboard interrupt, and screen - 
buffer, as the API calls of Table 2.1 indicate. 

OS/2 reserves the right to redefine memory dynamically during program exe- 
cution. This is necessary to implement multitasking and memory management of 
huge segments (greater than 64K segments). Since OS/2 can access 16 Megabytes 
(MB) of actual memory because of the 24-bit physical address size, it must map the 
full virtual program memory into this space, or smaller, during program execution. 
The virtual memory access may contain up to a full gigabyte (2* bytes) of individu- 
ally addressable byte locations. 
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Clearly, physical address space is normally difficult to access and naturally 
remains the province of OS/2. In some cases, however, the programmer has access 
to this dimension. We will see a situation of actually writing to the OS/2 physical 
memory when the screen buffer 


TABLE 2.1 API SUBSET USED IN CHAPTER 2 


API function Comment 
DosOpen Open specified device or file 
DosExit Terminates active threads and processes 
DosWrite Transfers the specified bytes from a buffer to the specified file 
DosClose Closes the specified device or file 
VioScrollUp Scrolls the screen upward 
VioSetMode Sets the graphics or alphanumeric screen mode 
VioScrLock Locks the physical display buffer context 
VioGetPhysBuf Retrieves a segment selector for the physical display buffer 
VioScrUnLock Unlocks the physical display buffer context 
KbdStringIn Loads a keyboard buffer with a character string 


is accessed in a subsequent example. It is possible to gain access to the screen 
buffer by locking the screen context and then using a segment selector returned by 
OS/2 for writing directly to the physical buffer containing the screen addresses. This 
differentiates the IBM physical screen buffer, with its fixed physical locations in 
memory, from other RAM addresses, which can vary in dynamic but protected fash- 
ions under OS/2. 


2.2 INTRODUCTORY ASSEMBLER PROGRAMMING 


As indicated earlier, we have assumed that the reader has a background in both 
80286 assembler and the C language. This book does not teach either, but we do 
provide a brief review of the syntax associated with the languages. In this section 
we examine the macro assembler that is compatible with the Protected Mode. 
Appendix A contains the Macro Assembler/2 instructions and pseudo-ops. 


2.2.1 The IBM Macro Assembler/2 


There are two reasons why programmers should be interested in assembly languages. 
First, assembler provides an understanding about both the underlying software archi- 
tecture for a given microprocessor and the needed chip interfaces for a given micro- 
computer. Second, situations can arise where other languages are inadequate for 
achieving optimized performances. The Macro Assembler/2 has basically the same 
features as other Intel assemblers. The dominant active instruments in the assembler 
are the instructions with the form 
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[label] instruction-mneumonic [operand(s) ] [;comment ] 


Here the brackets indicate that the quantities contained within are optional depend- 
ing on instruction type. The instruction sequence 


mov cx,1000 ;load loop limit 


mov si,O sinitialize index 

DO11: ;label for loop 
mov ax,Si sload ax with index 
sub ax,100 ssubtract 100 from index 
cmp ax,0 scheck to see if zero 
je ELSE1 sjump if zero to ELSE1 
inc si sincrement index 
loop DO11 ;loop back to DOl11 


ELSE1: 


is an example of the use of the move(mov), subtraction(sub), jump-if-equal(je), 
increment(inc), compare(cmp), and loop instructions. Note that the labels DO11 and 
ELSE1 go with the next line of code. In this fragment the loop instruction decre- 
ments cx each time. When ax becomes zero the jump takes place to the target label 
ELSE1. This very brief illustration of the assembler instruction usage is intended as 
an example of the IBM Macro Assembler/2, MASM. For a complete discussion of 
the assembler instructions, consult the Language Reference Manual [4]. 

In addition to the instructions the assembler has a class of statements that 
provide information about the program environment. These statements do not result 
in machine code and are referred to as pseudo-ops. Typical of the pseudo-ops is the 
SEGMENT directive, which is used to demarcate the various segment definitions 
within the source code. The SEGMENT pseudo-op has the form 


sequence SEGMENT © align-type combine-type ‘class’ 


where segname is the name of the segment. Align-type indicates how the segment 
begins in memory [PARA: paragraph boundary [address divisible by 16]; BYTE; 
WORD; or PAGE: last 8 bits of address are zero], and combine-type indicates how 
the segment is to be linked [PUBLIC: all public segments with the same name are 
linked; COMMON: all segments with the same name overlap; AT(exp): segment 
located at nearest paragraph to “exp”; STACK: stack segment; and MEMORY: 
higher addresses than other segments]. The designator ‘class’ refers to a collection 
of segments with the same class name. Segments end with 


segname ENDS 


To define segment type the ASSUME pseudo-op is used to associate a name 
with a segment register: 


ASSUME CS:segname, SS:segname[,DS:segname[,ES:segment] ] 
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Here CS is required and SS is required when a stack segment is present. Both DS 
and ES are optional. We could continue to enumerate the Macro Assembler features; 
however, the best technique for elucidating the language is through illustration. In 
the following section we consider such an example. 


2.2.2 An Example Program: Printer Control 


Figure 2.1 contains an assembler program that causes the printer to print in graph- 
ics mode under OS/2. The program opens with two pseudo-ops: PAGE and TITLE. 
PAGE has the form 


PAGE operand1,operand2 


The entry in operand1 indicates the number of horizontal lines per page in the as- 
sembler listing (here it is 55). Operand2 is the number of characters per line in the 
listing. The TITLE pseudo-op specifies the title on the first line of each assembler 
listing page. Spread throughout the program are semicolons. All text following a 
semicolon on the same line is treated as a comment. The pseudo-op IF1 (a condi- 
tional pseudo-op) indicates that all instructions and pseudo-ops following it and prior 
to the next ENDIF are to be implemented during pass 1 of the assembler. In Figure 
2.1 the file sysmac.inc is to be included at this point. 

Sysmac causes doscalls.inc and subcalls.inc to be included which set up 
macros for all API calls that appear in the subsequent code segments. The pseudo- 
op .sall causes macro listings to be suppressed. Next follows the GROUP pseudo-op. 
This pseudo-op collects the data segment under the name dgroup: 


dgroup GROUP data 
The stack segment follows. Here 256 copies of the string 
STACK.. 


are used to form the stack segment. This should be more than adequate for the stack 
size required by most small programs. The pseudo-op, db, stands for define byte and 
the dup operator duplicates the 8-byte string within parentheses, 

The data segment follows and requires some explanation in conjunction with 
the API calls that are in the code segment. Consider first the variables defined in 
this data segment that begin dev_... . There are eight of these variables and they are 
defined in reference to the @DosOpen API macro call. Consider the form of this 
call in the code segment 


@DosOpen dev_name,dev_hand,dev_act,dev_size, 
dev_attr,dev_flag,dev_mode,dev_rsv 


This API call opens a file with file path name dev_name. The path is the zero-ter- 
minated string: ‘LPT1’,0. The file handle is returned with dev_hand. The action 
taken is returned in dev_act, where 
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PAGE 55,132 
TITLE PRT2 - This is the initial printer routine (PRT2.ASM) 


include sysmac.inc 


ENDIF 


e 


-sall 
dgroup GROUP 


‘ 
STACK SEGMENT 


db 


STACK ENDS 


‘ 
DATA SEGMENT 


in_buffer 
in_leng 
bytesin 
bytesout 
in_bufferl 
bytesinl 
in_buffer2 
bytesin2 
in_buffer3 
bytesin3 
in_buffer4 


e 
Ul 


dev_name 
dev_hand 
dev_act 

dev_size 
dev_attr 
dev_flag 
dev_mode 
dev_rsv 


DATA ENDS 


data 


PARA STACK 'STACK' 
256 dup('STACK ) 


ab 
aw 
aw 
aw 
dab 
dw 
ab 
aw 
ab 


PARA PUBLIC 'DATA' 


400 dup(0) 


DESCRIPTION: This program simply prints a "74" in 
graphics mode (320 times) for two lines which are 
meshed together. 


;Suppresses macro lists 


$ - offset in_buffer 


320 
) 

1BH, 4BH, 64D, 01H 
4 

ODH, OAH 

2 

1BH, 41H, 08H 

3 

1BH, 32H 


'LPT1',0 
0 

0 

0 

0 
00000001b 


0000000011000001b ;Hdl private,deny none,w/o 


0 


, 

CSEG SEGMENT PARA PUBLIC 'CODE' 
ASSUME CS:CSEG,DS:DATA,ES:DATA,SS:STACK 

PRTSC1 PROC 
push ds 


pop es 


FAR 


7320 columns 


;Open File 


e 
’ 


;Open LPT1 as device 


Chap. 2 


@DosOpen dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag,dev_mode,dev_rsv 
cmp ax,0 
je ELSE1 


@DosExit 1,0 


mov 
mov 


mov 
mov 
ine 


cx, 320 
si,0O 


al,74 


in_buffer(si],al 


si 


loop LOOP1 


Figure 2.1 Assembler program prt2.asm, which prints printer graphics under 
OS/2 Protected Mode. 


;Exit 


7320 columns 
sinitialize index 


spins 2,4,5, and 7 
;load printer write buffer 


-stincrement buffer index 


;Set lptl vertical spacing 
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@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 

;Activate spacing 
@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 

;Initialize printer graphics 
@DosWrite dev_hand,in_bufferl,bytesinl,bytesout 

;Write print buffer 
@DosWrite dev_hand,in_buffer,bytesin,bytesout 

7;CR & LF 
@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 

;Reset graphics mode 


@DosWrite dev_hand,in_bufferl,bytesinl1,bytesout 

;Write print buffer again 
@DosWrite dev_hand,in_buffer,bytesin, bytesout 

;Close device 


@DosClose dev_hand 
;Exit 
@DosExit 1,0 
PRTSC1l endp 
CSEG ends 
end PRTSC1 


Figure 2.1 (Concluded) 


0001H = file exists 
0002H = file created 
0003H = file replaced 


Here the file’s size in bytes is returned in dev_size. The file attribute bits are de- 
fined as follows: 


0001H = read only file 
0002H = hidden file 


0004H = system file 
0010H = subdirectory 
0020H = file archive 


with other dev_attr combinations corresponding to reserved values. Dev_flag speci- 
fies the action to be taken if the file exists, where 


00000001B 
indicates that the file should be opened. The dev_mode parameter has the form 


15 0 


bit: DWF RRRRR#dISsS&sS SRAAA 


where 
D = Q means open in normal way 
W = 0 writes may be run through the DOS buffer cache 
F = 0 errors reported through system error handler 
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R = 0 reserved and must = 0 

I = 1. file handle is private to the current process 
SSS = 100 deny neither Read nor Write access 

AAA = 001 Write only access 


Hence 
dev_ mode dw 0000000011000001B 


corresponds to file handle private, deny none, and write only. The parameter dev_rsv 
must be zero. We will return to the remaining data segment variables as the code 
segment API calls that use these variables are considered. 

Following the termination of the data segment, DATA, the code segment is 
developed. This segment, CSEG, opens with an ASSUME pseudo-op that associates 
each segment register with an appropriate segment name. Here both DS and ES are 
associated with DATA. Next a FAR procedure PRTSC1 is set up. Notice that the 
normal DOS program segment prefix (PSP) area is not required. The return is FAR 
and will be accomplished using 


@DosExit 1,0 


which automatically returns execution to the proper OS/2 entry point at the close of 
PRTSC1. In this API call the first parameter is set to 1 and causes all threads in the 
process to end. The second parameter is the result code, and this is used by any 
threads requiring input from the process prior to its termination. 

Upon entry to PRTSC1, DS is pushed on the stack and popped into ES. Then 
@DosOpen is called as discussed above. The return value from this call is in ax 
and, if 0, means that a normal open occurred. If ax is not zero, @DosExit is called. 
To understand the remaining instructions and macro calls, it is necessary to under- 
stand how the printer works in graphics mode. The @DosOpen macro opens LPT1 
(the line printer) as a file. This file can be written using the @DosWrite macro. The 
line printer used in this example is an EPSON FX-85 [5]. The @DosWrite macro 
can be used to pass characters for output to the printer as well as passing control 
codes. We would like to use the printer in graphics mode. 

The print head consists of a vertical array of eight pins. In graphics mode 
these pins have an associated weight as follows: 


PIN WEIGHT 


0 128 
° 64 
0 32 
o 16 
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Here three pins have been darkened to indicate that they are active. The total sum 
of the pin values for these darkened pins is 74; hence when in graphics mode, a 74 
output to the printer will cause these pins to print. Similarly, 255 would cause all 
pins to print. Also, 128 would cause only the top pin to print. 

How is the printer placed in graphics mode? Most of the printer control char- 
acters are of the form ESC... . To put the printer in single-density graphics mode the 
sequence 


ESC “K” (nl) (n2) 
must be sent. Using ESC = 1BH and “K” = 4BH, it follows that if 


nl = d MOD 256 
n2 INT (d/256) 


where d = total number of columns to be printed, then 
1BH, 4BH, 64D, D1H 


corresponds to setting the printer in the graphics mode with a total of 320 printer 
columns active, out of a possible 480 for the FX-85. 

Returning to the code appearing in Figure 2.1, we see that the buffer, 
in_bufferQ, is loaded with 320 values of 74 (the character value corresponding to 
the pins discussed earlier). Following the loading of this buffer the macro call 


@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 
is made. Here 
in_buffer3 = 1BH,41H,08H 


where the first character is ESC. The second character sets the vertical spacing to 
8/-inch line spacing: 


ESC A (8) 


The third parameter in all the @DosWrite calls is the buffer length, and the 
fourth parameter is the number of bytes written. The macro call 


@DosWrite dev_hand, in_buffer4,bytesin2,bytesout 
executes 


ESC 2 
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which implements the line spacing set above. The macro call 
@DosWrite dev_hand,in_bufferl,bytesinl,bytesout 
sets up the call 
ESC K 64 1 


to specify 320 columns. This command must be followed by 320 characters. The 
command 


@DosWrite dev_hand,in_buffer,bytesin,bytesout 


outputs 320 columns, corresponding to the 74 graphics combination already illus- 
trated. 
Next 


@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 


causes ODH and OAH to be output for the carriage return and line feed. This is fol- 
lowed by a reset of the graphics mode and a second print of the 320 values of the 
graphics mode 74. Figure 2.2a illustrates the output for this program. When the 
buffer value is changed from 74 to 255, all pins print. This case is illustrated in 
Figure 2.2b. : 


(b) 


Figure 2.2 Printer output from prt2.asm (a) with fill character “74” and (b) 
with fill character “255”. 


The program appearing in Figure 2.1 illustrates the main features of how to ac- 
cess the API from assembler. Here the printer was accessed using API calls and 
placed in graphics mode as well as used to output graphics characters. In the next 
section we look at more complex programs that access the screen buffer. Since we 
have information about the screen pixels, it will be possible to develop a screen 
print program that uses the printer in graphics mode to print the screen. 
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2.3 ACCESSING THE VIDEO SERVICES 


To be able to access the screen context requires a knowledge of the physical 
memory associated with the display. This memory has different partitioning depend- 
ing on what display mode is being used. Typically, the graphics modes normally ac- 
cessed by the IBM PS/2 computers (and the IBM AT) are Color Graphics Adapter 
(CGA) mode, which is a 320-column by 200-row pixel screen, the Enhanced Graph- 
ics Adapter (EGA) mode, which is a 640-column by 350-row pixel screen, and the 
Video Graphics Adapter (VGA) mode, which is a 640-column by 480-row pixel 
screen. 


2.3.1 The Display Buffer 


In this chapter we access the CGA screen context. This is mode Hex 5. The 
memory is allocated into two buffer regions specified as follows: 


1. Even Scans (rows 0, 2, 4, ..., 198) starts at address B8000H. 
2. Odd Scans (rows 1, 3, 5, ..., 199) starts at address BAOOOH. 
3. Each raster row occupies 80 bytes, where a byte has the following form: 


Pixels: N N+1 N+2 N+3 


Cl co Cl co Cl Co Cl co 


with color section determined by 


Ci Co 

0 0 black 

0 1 light cyan 

1 0 light magenta 

1 1 intensified white 


4. Address B8000H contains the pixel information for the first four pixels in the 
upper left-hand corner. 


There is a second CGA mode, which is 640 columns by 200 rows; however, we 
will not consider this mode. We use the terms pel and pixel interchangeably herein. 

How does the actual location of a pixel attribute get set based on row and 
column data about the screen? To locate the correct (row, col) byte in screen buffer 
physical memory, it must be remembered that the even-row value starts at location 


80 * (row/2) 


offset from B8000H. Similarly, recognizing that integer division truncates (3/2 
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becomes 1, ...), the same expression serves to locate an odd-row relative to 
BAOOOH. Since there are 80 bytes for 320 columns, we need to locate 


col/4 
‘Hence the offset location of a given byte in terms of (row,col) is given by 
80 * (row/2) + (col/4) 


This would correspond to the code 


mov ax,row 

shr ax,l 

mov dx,0 ; clear upper 
mul eighty 

mov bx,col 

shr bx,1l 

shr bx,1l 

add ax,bx 


To identify an individual pixel within a byte, we note that the least significant 
bit (LSB) and LSB+1 correspond to the attribute positions for the fourth pixel, 
(LSB+2, LSB+3) correspond to the attribute positions for the third pixel, and so on. 
Hence 


Bit: 7 6 5 4 3 2 1 0 


Pixels: 1 1 2 2 3 3 4 4 


We will simply turn the pixel on using a mask: 
MASK1 = 01H 


This will produce a light cyan screen color. Dividing col by 4 generates a remain- 
der (0,1,2,3), which is in reverse order to the pixel number (assuming that we start 
numbering the pixels within a byte 0,1,2,3). Hence 


3-col mod 4 

indicates the actual pixel position within the (row,col) byte. Starting with 
00000001 

it is clear that a shift 


2 * (3-col mod 4) 
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will place 1 in bits 6, 4, 2, or 0 as needed to specify the pixel attribute. The follow- 
ing code uses the coprocessor to load xxx with this pixel value based on row, col: 


fild four 

fild col 

fprem ;modulo 
fistp xx 

fistp dummy 


mov 
mov 
sub 
mov 
mul 
mov 


al,3 

bl,byte ptr xx 

al,bl 

ah, 0 

two 

cl,al 

al,MASK1 *MASK1 = 01H 
al,cl 

xxx,cl 


This, then, is a prescription for using a screen direct memory access (DMA) tech- 
nique to the video physical buffer, once that buffer has been accessed. 

The last code necessary to complete specification of a video buffer location is 
to specify the precise offset location for address above. Here we assume that the 
even-row or odd-row location must also be taken into consideration. Consider the 


code 


mov ax,row 
and ax,MASK11 *MASK11=0001H 
cmp ax,0 
jle ELSE1 
mov ax,address 
add ax,OFFSET1 sOFFSET1 = 2000H 
jmp IF11 


ELSE1: 


mov ax,address 


IF11: 


mov bp,ax 
mov al,xxx 
or es:[bp],al 


This code checks to see if the row is even or odd. If odd, an offset of 2000H 
is added to address. The full pixel byte offset is in address and the byte value in 
xxx. Assuming that the extra segment register contains the video segment selector 
value, then 
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ov es:{bp],al 
changes the bit values from 00 to 01 as needed for the pixel in question. 
2.3.2 Locking the Screen Context 


Figure 2.3a presents a function flowchart for a program that plots two lines across 
the screen. Figure 2.3b illustrates this program, which calls the video buffer and 
plots two parallel lines across the screen. The program also calls a routine scr_ld 
that loads an intermediate buffer, scr_buffer, with the screen context pixel values. 
This buffer is then used to output the display context to the printer. We will not 
focus on the routines that write the display context to the printer until Section 2.3.3. 
In this section we examine the video API calls. 

Consider the first executable instruction in the program the call to cls to clear 
the screen. The procedure cls, in turn, has a single call (besides the return): 


@vioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


The parameters appearing in this API call are among the first nine parameters 
appearing in the data segment. Viohdl is a handle to the display. The parameters tr 
and Ic are the top row and left column to be scrolled. The parameters br and vc are 
the bottom row and right column to be subtended for the scroll operation. A pa- 
rameter no_line is the number of lines to be scrolled and blank the attribute to be 
used to replace each character (in this case a blank) pair. This routine effectively 
blanks the screen. 

Next the main FAR procedure sets the screen in CGA graphics mode. To do 
this the video API call is made referencing the video handle and a CGA structure 
that contains parameter data: 


@VioSetMode CGAm,viohdl 


The video CGA structure is specified in the data segment by the required parame- 
ter values between the statements 


CGAm label FAR 

vrCGA dw 200 
where the last value is the number of rows (the vertical resolution) on the CGA 
screen. Below this structure in the data segment is a second structure, STDm, which 


is used later with the call to return to text 80 x 25 mode. This structure spans the 
lines between 


STDm label FAR 


vr80 dw 400 
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SETUP BUFFER & 
DATA AREAS 


CLEAR SCREEN 


SET CGA MODE 


RE-CLEAR SCREEN 


LOCK DISPLAY 
CONTEXT 


GET PHYSICAL 
BUFFER 


DRAW LINES 


SETUP TEMPORARY 
PLOT BUFFER 


UNLOCK SCREEN 


HESITATE DISPLAY 


RETURN TO 
STANDARD MODE 


PRINT DISPLAY 
CONTEXT 


EXIT 
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Figure 2.3a Functional flowchart for 
boxprtl.asm, the program that calls the 
video buffer and plots two lines. 
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TITLE BOXPRT1 - This program checks print graphics (BOXPRT1.ASM) 


-~e %e te we & 


- 8087 


PUBLIC xx,xxx 
EXTRN prtscr: FAR,scr_1d:FAR 


IFi 


include sysmac.inc 


ENDIF 


’ 


-sall 
agroup GROUP 


v 
STACK SEGMENT PARA STACK 
256 dup('STACK 


db 


STACK ENDS 


‘ 
DATA SEGMENT PARA PUBLIC 
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data 


DESCRIPTION: This program plots two lines in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 


;CodeView symbol map 


;Suppresses macro lists 


PUBLIC in_buffer,bytesin, bytesout,in bufferl,bytesinl 
PUBLIC in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
PUBLIC dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 


PUBLIC dev_mode,dev_rsv,MM,coli,N 


PUBLIC s,eight,eighty, four,shift1,scr_buffer 


PUBLIC sixforty,N4,ddd,w,bl 


viohdl equ 


result dw 


action equ 


tr dw 
le dw 
br aw 
re dw 
no_line dw 
blank dw 


' 
CGAm label 


lmodeE dw 
typeCGA db 
COlCGA db 
txtcCGA dw 
txtrcCGA daw 
hrcCGA aw 
vrCGA aw 


STDm label 


lmodes0 dw 
type80 db 
cols0 db 
txtc80 dw 
txtr8s0 dw 
hrs0 aw 
vr8s0 aw 


kbd_buf db 


lkbd_buf dw 


iowait dw 
kbdhdl 
waitf 
dastat 


12 
00000111B 
2 

40 

25 

320 

200 


FAR 
12 
00000001B 


$-kbd_buf 
0 
) 


;Required video handle 
;Completion code 
?Terminates current thread 
;TOp row screen clear 
;Left column screen clear 
;Bottom row screen clear 
7Right column screen clear 
sNumber lines scrolled 
;Blank character pair 


:Video mode structure-CGA 
;Structure length 

;Mode identifier 

;Color option-Mode 5 

;text characters/line-ignore 
;text lines-ignore 
shorizontal resolution 
svertical resolution 


;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

;text lines 

shorizontal resolution 
svertical resolution 


*Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


Figure 2.3b Program code for boxprtl.asm. 
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e 


PVBPtr1 label FAR ;Video buffer structure 
bufstl dd OB8000H ;Start physical address 
buflenl dd 4000H ;Buffer length 

physell dw ¢) 70S/2 screen buffer selector 


MASK1 db 01H ;PEL byte mask 

MASK11 dw 0001H ;Odd/even row mask 
OFFSET1 dw 2000H Odd row buffer offset 
four dw 
xX dw 
dummy dw 
two ab 
XXX ab 
eighty dw 
row dw 
col aw 
address dw 


PEL modulo parameter 
780287 dummy "pop" 


;Output value 
;row 


;column 
sAddress screen dot 


VV VO VN Vv & 


dw 2 7;Box col parameter 
dw ;Box row parameter 
dw ;Start column 

dw 7End column 

dw ;Start row 


rad 
on 


<< 
ooo 


td 
° 
, 
e 
, 
e 
o 
e 
v 
e 
7 
e 
e 


in_buffer 320 dup(0) ;print buffer 

bytesin dw 7CGA line 

bytesout 0 ;output count 
in_bufferl 1BH,4BH,64D,01H ;printer setup 

bytesinl 4 ;count bytes In_bufferl 
in_buffer2 ODH, OAH ;LF/CR 

bytesin2 2 ;in_buffer2 byte count 
in_buffer3 1BH, 41H, 08H 

bytesin3 3 ;in_buffer3 byte count 
in_buffer4 1BH, 32H 


’ 


dev_name 'LPT1',0 sname of printer device 

dev_hand 0 ;device handle 

dev_act 0 

dev_size 0 

dev_attr 0) 

dev_flag 00000001b ;Open File 

dev_mode 0000000011000001b shdl private,deny none,w/o 
dev_rsv 0 ;reserved 

N4 ? 

MM 40H,10H,04H,01H ;pel mask 

Ww 128,64,32,16,8,4,2,1 ;pin weights 

coll 320 dup(?) ;column index-printer 

bl 4 dup(?) 

N ? 
shift1 6,4,2,0 
s 4 dup(?) ;dup copies pel byte 

dda ? 

sixforty 640 

scr_buffer 16384 dup(0) ;temporary buffer--screen values 


sprinter line 


Figure 2.3b (Continued) 
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SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dadgroup 
PROC FAR 


call cls 
@vioSetMode CGAm,viohdl 
call clsCGA 


@vioScrLock waitf,dstat,viohdl 
@VioGetPhysBuf PVBPtri1,viohdl 
push physell 

pop es 


mov ax,0 
mov y,ax 
call lineh 
mov ax,100 
mov y,ax 
call lineh 


call scr_ld 


@VioScrUnLock viohdl 


@KbdStringIn kbd_buf,1lkbd_buf, iowait, kbdhdl 


@vioSetMode STDm,viohdl 
call prtscr 
@DosExit action,result 


ENDP 


PROC NEAR 
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;Clear screen 
:Set CGA Graphics mode 
7Clear CGA screen 


Lock screen context 

7Get physical buffer selector 
:Save selector 

:Load selector into extra segment 


:;Draw line 


:araw second line 


e 
’ 


e 
e 
e 
’ 


Unlock screen context 
shesitate 


780 x 25 alpha mode 


;Terminate process 


@VioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


ret 
ENDP 


PROC NEAR 


@VioScrLock waitf,dstat,viohdl 
@VioGetPhysBuf PVBPtri1,viohdl 
push physeli 

pop es 


mov 
mov 


bp, 0 
al,0O 


mov es: [bp],al 
inc bp 

cmp bp, 1F3FH 
jle Dol 


bp, 2000H 
al,0 


es: [{bp],al 
bp 
bp, 3F3FH 


;Lock screen context 
;Get physical buffer 
;Screen selector 
;Load extra segment 


;Start offset zero 
;Zero attribute-clear 


;Clear byte 
7;Check end 1st buffer 
;Offset 2nd buffer-odd 
7Zero attribute-clear 
:Clear byte 


7Check end 2nd buffer 


Figure 2.3b (Continued) 
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; 
clsCGA 


wdot 
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jle DO2 
@VioScrUnLock viohdl 


ret 
ENDP 


PROC NEAR 


(col,row) = (x,y) 
fild four 

fild col 

fprem 

fistp xx 

fistp dummy 

mov al,3 

mov bl,byte ptr xx 
sub al,bl 

mov ah,0O 

mul two 

mov cl,al 

mov al,MASK1 

shl al,cl 

mov xXxx,al 


ax, row 
ax,1 
ax,0 
eighty 
bx,col 
bx,1 
bx,1 
ax, bx 
address ,ax 
ax, row 
ax, MASK11 
cmp ax,0 
jle ELSE1 
mov ax,address 
add ax,OFFSET1 
jmp IF11 


mov 
shr 
mov 
mul 
mov 
shr 
shr 
add 
mov 
mov 
and 


mov ax,address 


mov bp,ax 
mov al,xxx 


or es:[{bp],al 


ret 
ENDP 


PROC NEAR 


row position, xb = begin, xe 


ax,y 
row, ax 


ax,0 

xb,ax 
ax,319 
xe,ax 
ax, xb 


Figure 2.3b 
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7;Unlock screen context 


;Load stack with 
7ST = col, ST(1) 
:Modulo 

;Store remainder 
;Pop stack 


7(3 - col % 4) 
;Clear upper multiplicand 


;Shift value for PEL 
7;PEL color mask 
:Shift to correct PEL 
7;Store buffer value 


° 
e 


;Begin address calculation 
;Divide row by 2 

;Clear upper multiplicand 
;Convert column value to bytes 
;0ffset in ax 

;Save offset base 


?Check even/odd row 
:Look for bit 0 set 


sadd odd buffer offset 


s;screen buffer address 
;Attribute value for dot 


;Write dot 


= end 


:Establish row for wdot 


° 
’ 
e 
, 


x~begin position for line 
7x~end position for line 


sEstablish start column 


(Continued) 
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mov col,ax 

push ax ;Save column value 

call wdot ;Write dot (col, row) 

pop ax ;Recall column 

inc ax :Increment column 

cmp ax,xe ;Check end horizontal line 


jle DO10 

; 
ret 
ENDP 


ENDS 
END 


Figure 2.3b (Concluded) 


appearing in the data segment. Finally, a call to clsCGA is made, which reclears the 
screen in CGA mode. This call is needed because the switch to CGA mode leaves 
the screen in an unpredictable state. The call to clsCGA is somewhat different than 
the prior cls call because the screen is now in CGA mode and the screen context 
must be locked prior to accessing it. 

In the procedure clsCGA, the first executable statement is the macro call 


@VioScrLock waitf,dstat,viohdl 


This call locks (or requests ownership) of the physical display buffer. The flag waitf 
is 0 if the screen is not available; otherwise, it is 1. The status, dstat, is 0 if the lock 
is successful; otherwise, it is 1, and viohdl is the video handle. Once this routine is 
executed the physical buffer may be accessed. This is accomplished using the state- 
ment 


@vVioGetPhysBuf PVBPtrl,viohdl 


Here PVBPtrl is a structure with the form (see data segment) 


PVBPtr1l label FAR 


bufstl dd 0B8000H 
buflenl dd 4000H 
physell dw 0 


The first parameter in this structure, bufstl, is the start address of the physical dis- 
play buffer specified as a 32-bit physical address. We see that this is merely the 
beginning of the CGA even-row buffer space, as described above for normal IBM 
memory allocation (B8000H). The second parameter, buflen1, is the length of the 
buffer, which is 4000H or 16384 bytes long. Finally, physell is the physical selec- 
tor which is returned by the call. Upon completion of the call the physical selector 
value is immediately loaded in the extra segment register es. Hence, es then points 
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to the beginning of the physical buffer. This step is very important because it 
confirms the translation of the segment registers and the segment arithmetic for 
calculating a physical or virtual address. Following the loading of the selector 
address, the two buffer regions are cleared: even rows (offset 0-1F3FH) and odd 
rows (offset 2000H-3F3FH). Then the screen context is unlocked with the call 


@VioScrUnlock viohdl 


The actual screen write is accomplished using two calls to the procedure lineh, one 
call at y value 0 and one call at y value 100 (halfway down the screen). The form 
of lineh use in this program merely draws a straight horizontal line from column 0 
to column 319 of the screen. The actual drawing of the dot is accomplished by a 
procedure wdot, which implements the techniques of section 2.3.1 discussed earlier. 

Following the plotting of the two horizontal lines on the display, the screen 
context is loaded in the buffer, scr_buffer, based on a call to scr_ld. Eventually, the 
screen is printed using prtscr, which employs this buffer as a template of the screen 
context. The screen is next unlocked and the keyboard pause or hesitation is insti- 
tuted with the call 


[@kbdStringIn kbd_buf,1lkbd_buf,iowait,kbdhdl 


Here kbd_buf is a buffer for a character string that is 80 bytes wide. The variable 
1kbd_buf is the length of this buffer. A value of 0 for iowait indicates that the 
system should wait or hesitate if a character is not available. The parameter kbdhdl 
is the handle to the keyboard device context. This call, of course, pauses the action 
and allows the user to view the screen. 

The second call to @VioSetMode returns the video context to 80 x 25 text 
mode. Calling prtscr prints the intermediate screen buffer on the printer as described 
above. Finally, @DosExit causes the program to exit back to OS/2. Figure 2.4 is the 
actual print of the screen output. 
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Figure 2.4 Output print screen from boxprtl.asm (Figure 2.3b). 
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2.3.3 Printing the Graphics Screen under OS/2 


In Figure 2.3 a portion of the data segment was devoted to parameters and variables 
used by scr_Id and prtscr for the printer dump of the screen context. These variables 
appeared earlier in the program of Figure 2.1, where a simple graphics print output 
was generated. In this section we address the topic of how to achieve a printout of 
the graphics screen context. This is similar to employing GRAPHICS.COM under 
DOS except that our screen print program does not run in the background but is 
directly callable by the program executing. IBM and Microsoft did not provide the 
equivalent of GRAPHICS.COM with their system software during the early releases 
of OS/2. Hence this program is both useful for obtaining a hard copy of the graph- 
ics screen and as information for illustrating the combined techniques of display 
access and graphics printer output. 

We have seen how to access the screen physical buffer using API calls. Also, 
we saw a routine, scr_ld, used ostensibly to load a buffer scr_buffer. Figure 2.5 
illustrates this routine and we see it is a very simple procedure with no API calls. 
Only the byte array, scr_buffer, is external. The routine also interleaves the even and 
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TITLE SCRLD -- This routine loads the screen print buffer (scrld.asm) 


DESCRIPTION: This routine accompanies prtscr to load 
and print the screen in 320 x 200 mode. 

The prtscr buffers are assumed loaded. This is an OS/2 
routine. 


scr_buffer: BYTE 

-sall 

SEGMENT PARA PUBLIC 'CODE' 

PUBLIC scr_ld 

PROC FAR 

ASSUME CS:CSEG 

mov cx,100 ino. of raster pairs 
mov di,O ;index to screen buffer 
mov si,O ;index to dummy array 


push cx 


mov cx,80 


mov al,es: [di] 

mov ah,es: [di+2000H] 
lea bx,scr_buffer[0] 
mov ds: [bx+si],al 
mov ds: [bx+si+80],ah 
inc si 

inc di 

loop DO56 


add si,80 
pop cx 
loop DO55 


ret 
ENDP 
ENDS 
END 


;raster row length 


;load even row physical buffer 
;odd row physical buffer 
;dummy buffer 

;load even rows 

;0dd rows 


e 
, 


;skip to next double set 


Figure 2.5 Routine to set up temporary screen print buffer. 
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odd rows from the physical buffer regions into a single buffer area which represents 
the full screen context in contiguous fashion. 

Figure 2.6a illustrates the function flowchart for the print screen routine. Figure 
2.6b contains the actual print screen routine. All the printer parameters referenced in 
the earlier data segments appear as external variables and are defined as such at the 
beginning of the program. Following the usual loading of sysmac.inc, the program 
starts immediately with the code segment, CSEG. The routine prtscr is declared 
PUBLIC. In general, our approach will be to treat prtscr and scr_Id as externally 
callable modules whenever a printer screen dump is desired. Hence these two 
modules will become workhorse functions for illustrating graphics displays and the 
reader can expect to encounter them throughout the book. Shortly we will install 
them in a general-purpose library GRAPHLIB.LIB where they will be universally 
accessible. The only difficult part about programming in this fashion is the large 
data segment areas that are needed to set up the calls to these printer procedures 
(and the screen parameter areas). 

Returning to Figure 2.6, we see immediately the usual call, @DosOpen, to 
open the printer device context. This was discussed in reference to Figure 2.1. Since 
this program returns to a calling procedure, the ret instruction is implemented rather 
than @DosExit. The sequence of API calls to @DosWrite is generally in agreement 
with the earlier programming of Figure 2.1 except that the double output is omitted. 
A loop is set up to increment 25 times, once for each eight-line graphics print. This 
yields a total of 200 rows displaced vertically. These rows correspond to the actual 
screen buffer rows for the rasier scan. Since each row of the screen buffer consists 
of 80 bytes of pixel data, eight rows at a time correspond to blocks of 640 bytes of 
data. : 

The call to Idarray sets up the output for the printer eight rows at a time. 
Basically, a small 32-element buffer, col1[], is loaded with the four pixels’ worth of 
data contained in each byte of the physical display buffer. This is done for the same 
byte from eight consecutive rows of the screen buffer. Hence Idarray sets up a group 
of pixel data representing a block of the screen context. To do this an array of four 
elements, s[OQ] to s[3], is loaded with a byte of the screen buffer data from 
scr_buffer. Each pixel is then masked off from its position in this byte, shifted, and 
weighted to generate the correct graphics printer character. The weights, for ex- 
ample, contained in the array, w[], must be specified in the calling program’s re- 
served printer data area in the usual fashion. It is this technique that is used to load 
the array coll1[]. : | 

Returning to prtscr itself, we see that after each eight-line block by 320 col- 
umns is loaded and in_buffer[] properly loaded the graphics print is implemented. 
This is in the fashion of Figure 2.1 and is followed by a carriage return and line 
feed. Once the complete screen dump to the printer has been accomplished, prtscr 
closes the printer device handle with 


@DosClose dev_hand 


and returns to the calling routine. 
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OPEN PRINTER 
DEVICE 
S 
N 
INCREMENT CLOSE PRINTER 
LINE COUNT DEVICE 
LOAD EXIT 
PRINTER ARRAY 


INCREMENT 
ROW POINTER 
LOAD 
PRINTER BUFFER 


WRITE 
PRINTER BUFFER 
LF &CR 
INCREMENT BUFFER 
POSITION 640 


Figure 2.6a Functional flowchart for 
prtscr, the screen dump routine. 


Sec. 2.3 


Accessing the Video Services 


e 
J 
° 
’ 
e 
’ 

e 
’ 
e 
, 
e 
’ 
e 
a 
e 
, 
e 
’ 

e 
’ 
e 
s 
e 
’ 

° 
e 
e 
’ 
e 
e 
e 
e 
e 
’ 
e 
c 

° 
td 

° 
’ 

° 
’ 

° 
, 
e 
’ 

e 
’ 

° 
v 
e 
’ 

e 
, 

e 
’ 
° 
, 

° 
, 

. 
e 

° 
c 
. 
a 

° 
’ 

e 
‘ 
e 
c 

° 
s 

° 
c 

e 
, 
° 
e 

e 
‘ 
° 
a, 
° 
, 


Figure 2.6b 
captured. 
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prtscr - print screen (prtscr.asm) 


DESCRIPTION: This routine prints the screen in 
320 x 200 CGA mode. This routine needs the 
following data items in the calling routine 
data segment: 


in_buffer 320 dup(0) 
bytesin 320 

bytesout 0 

in_buffer1 1BH, 4BH, 64D, 01H 
bytesin1 4 

in_buffer2 ODH, OAH 
bytesin2 2 

in_buffer3 1BH, 41H, 08H 
bytesin3 3 

in_buffer4 1BH , 32H 


¢ 
dev_name 'LPT1',0 
dev_hand 0 
dev_act 0 
dev_size 0 
dev_attr 0 
dev_flag 00000001b 
dev_mode 0000000011000001b 
dev_rsv dd 
e 
40H,10H,04H,01H 
128,64,32,16,8,4,2,1 
320 dup(?) 
> 


e 


? 

4 dup(?) 

6,4,2,0 

8 

80 

4 dup(?) 

4 

? 
sci_buffer 16192 dup(0) 
sixforty 


MM: BYTE, w: BYTE, col1: BYTE 
in_buffer:BYTE,in_buffer1: BYTE, in_buffer2: BYTE 
in_buffer3: BYTE, in_buffer4: BYTE 

bytesin: WORD, bytesin1:WORD, bytesin2:WORD, bytesin3:WORD 
bytesout: WORD, dev_name: BYTE, dev_hand:WORD 
dev_act:WORD, dev_size:DWORD,dev_attr:WORD 
dev_flag:WORD, dev_mode:WORD, dev_rsv: DWORD 

N: WORD, N4: WORD 

eighty:WORD, eight:WORD, four:WORD,s: BYTE, shift1: BYTE 
scr_buffer: BYTE, ddd:WORD,b1: BYTE, sixforty:WORD 


include sysmac.inc 


-sall 


SEGMENT PARA PUBLIC 'CODE' 
PUBLIC prtscr 


Routine to print the screen once the physical display buffer is 
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prtscr PROC FAR 

ASSUME CS:CSEG 

;open device 

@DosOpen dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag,dev_mode,dev_rsv 

cmp ax,0 

je ELSE1 

;Exit 

ret 


;initialize device 
@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 
@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 
mov ax,25 ;number print lines(+1) 
mov si,O s;index to 8 row block 


push dx ;preserve dx 


push si :preserve block count 
mov ax,si 

mul sixforty 7640 block size 

mov N,ax ;Save in N 


° 
’ , 


call ldarray 


e 
’ 


mov dai,0O sinitialize 320 column counter 
mov cx,80 ;count of column bytes 


mov al,coli[di] ;column 1 from byte 

mov in_buffer[dij,al ;load print buffer 

mov al,coll1[(dit+1] ;column 2 from byte 

mov in_buffer[di+1],al sload print buffer 

mov al,coll[{di+2] ;column 3 from byte 

mov in_buffer[(di+2],al ;load print buffer 

mov al,coll[{di+t3] ;column 4 from byte 

mov in_buffer([di+3],al ;load print buffer 

add di,four ;increment column index 


loop LOOP2 


;write print row 
@DosWrite dev_hand,in_bufferl,bytesin1,bytesout 
@DosWrite dev_hand,in_buffer,bytesin, bytesout 
@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 


’ 


pop si 7recall block count 
pop ax ;recall print line count 
dec dx ;decrement count 
inc si ;increase block count 
cmp dx,0 ;check 25 lines printed 
jle DII1 

jmp LOOP1 


DIT1: 


@DosClose dev_hand 7Close print device 
ret 
prtscr endp 


ldarray PROC NEAR 
N is the printer row # - 640 byte intervals [0,24] 


MM[0O} = 40H,...,MM[(3] = 01H (pel mask) 
w([0O] = 128,w[{1] = 64,...,w{7] = 1 


me te we Me 


mov si,0O ;column count initialization 
mov cx,320 7320 columns 


mov al,0 ;clear print buffer 
mov coli{si],al 
inc si ;increment column count 


Figure 2.6b (Continued) 
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loop DO110 


mov si,O 
mov N4,si 
mov dax,80 


mov di,O 
mov ddd,di 
mov cx,8 


push cx 

mov bp,ddd 

add bp,N 

push bx 

lea bx,scr_buffer([(0] 
add bp,bx 

mov al,ds: [bp+si] 
pop bx 

mov s[(0},al 

mov s[1],al 

mov s[(2],al 

mov s[3],al 


and al,MM[0] 
mov cl,shifti[(0] 
shr al,cl 

mov ah,0O 

mul w[{di] 

mov b1[{0j,al 


mov al,s[1] 

and al,MM[1] 
mov cl,shifti1[1] 
shr al,cl 

mov ah,O 

mul w({dij 

mov bi1[{1},al 


mov al,s[2] 

and al,MM[2] 
mov cl,shift1[2] 
shr al,cl 

mov ah,0 

mul w[{di] 

mov b1[2],al 


mov al,s[3] 

and al,MM[3] 
mov cl,shift1[3] 
shr al,cl 

mov ah,O 

mul w[di] 

mov b1[3],al 


push bx 

mov bx,N4 

mov al,b1[0]} 

add coli[bx],al 
mov al,b1[1] 

add colli[bx+1],al 
mov al,b1[2] 

add coll[{bx+2],al 
mov al,b1[3] 

add coll[bx+3],al 
pop bx 
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& 

zindex into 80 bytes/row 
7;N4 = row byte block count 
;counter - row bytes 


;raster row counter (1 of 8) 
780 block counter 
sraster row counter 


preserve row count 

bp = # 80 byte blocks 

add printer line count 
preserve bx 

sload address screen buffer 
;add to index 

74 pel bytes 


. 
’ 
° 
’ 
e 
’ 
° 
’ 
° 


;1lst copy 

;2nd copy 

73rd copy 

74th copy 

zlst pel mask 

;load 1st pel shift 
sshift right 

;clear upper 

;multiply by weight (row) 
;save ist printer column 
s;load 2nd pel 

;mask 2nd pel 

;load 2nd pel shift 
;shift right 

;Clear upper 

;multiply by weight (row) 
;save 2nd printer column 
sload 3rd pel 

;mask 3rd pel 

jload 3rd pel shift 
;shift right 

;Clear upper 

smultiply by weight (row) 
ssave 3rd printer column 
’ 

sload 4th pel 

;mask 4th pel 

jload 4th pel shift 
;shift right 

;Clear upper 

;multiply by weight (row) 
;save 4th printer column 


e 
, 


;preserve bx 

;counter into print buffer 
;load column N4 

;load column N4+1 

;load column N4+2 


sload column N4+3 


Figure 2.6b (Continued) 
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pop cx ;recall print block row index 
inc di ;increase print block row counter 
add ddd,8s0 ;increase byte count 
dec cx ;decrease row bound 
cmp cx,0 
jle DO133 
jmp DO112 


add N4,4 ;add 4 columns to index 
dec dx ;decrement row bytes 
inc si ;increase screen buffer index 
cmp dx,0 
jle DII2 
jmp DO111 
DII2: 
ret 
ldarray ENDP 


CSEG ENDS 
END 


Figure 2.6b (Concluded) 


Figure 2.7a presents a Structure Chart for the modularized boxprtl.asm pro- 
gram. Figure 2.7b presents a modularized version of the earlier boxprtl.asm pro- 
gram. Here all the graphics and print routines have been assembled as separate 


modules. Only the large data segment areas are present with the small FAR proce- 
dure that actually plots and prints the two lines. 


000 


PLOT/PRINT 
TWO PARALLEL 
LINES 


200 300 
ACCESS PRINT 


SCREEN SCREEN 


210 220 


LOCK PLOT 
SCREEN & HORIZONTAL 
SET MODE LINES 


Figure 2.7a Structure Chart for modularized boxprtl.asm program. 


Figure 2.8 illustrates a module that is used to build GRAPHLIB.LIB, a graph- 
ics and print library. This module contains the routines needed by twoln.asm to 
develop the two-line output in modular fashion. There is only one difference: In the 
twoln.asm program the length of the lines must be specified in the routine lineh. 
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This was implemented to be 320 columns with the earlier version of lineh. That 
version was used with twolin.asm, and we have illustrated the more general lineh in 
Figure 2.8 because it is characteristic of what appears in GRAPHLIB.LIB. Here, the 
beginning and ending column values must be specified in xb and xe, respectively. 


PAGE 55,132 
TITLE TWOLN - This program plots/prints 2 lines (twoln.asm) 


DESCRIPTION: This program plots two lines in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 


=e te “8 “Ee TE 


- 8087 
EXTRN 
IF1 


prtscr: FAR, scr_ld:FAR,cls:FAR,C1SCGA: FAR, lineh: FAR 


include sysmac.inc 
ENDIF 


e 
, 


-sall 
GROUP 


;Suppresses macro lists 
data 


dgroup 


"STACK! 
') 


SEGMENT PARA STACK 
db 256 dup('STACK 
ENDS 


’ 
STACK 
STACK 


SEGMENT PARA PUBLIC 'DATA' 


Oo 
ie 
» 


eo se Me Ne Ne 


in_buffer,bytesin,bytesout,in_bufferl,bytesinl 
in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 

s,eight,eighty, four,shiftl 
sixforty,N4,ddd,w,b1,scr_buffer 


xx, xxx, tr,lc,br,rc,no_line,blank,viohdl, PVBPtr1,physeli,waitf 
dastat, four, two,col,dummy,MASK1,MASK11,row, eighty, address 
OFFSET1,y,xb,xe 


ese ~e 8 Me te MO 


;Required video handle 
;Completion code 
;Terminates current thread 


viohdl 
result 
action 


tr 

le 

br 

re 
no_line 
blank 


e 
’ 


CGAm 
lmodeE 
typeCGA 
colCGA 
txtcCGA 
txtrcGA 


;Top row screen clear 
;Left column screen clear 
Bottom row screen clear 


;Right column screen clear 


;Number lines scrolled 
7Blank character pair 


;Video mode structure-CGA 
;Structure length 
;Mode identifier 
;Color option-Mode 5 


00000111B 
2 
40 


25 ;text lines-ignore 


Figure 2.7b Modularized program twoln.asm. 


stext characters/line-ignore 
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hrCGA dw 320 shorizontal resolution 
vrCGA dw 200 :vertical resolution 
STDm label FAR ;Video mode structure-80x25 
lmode8s0 dw 12 ;Structure length 
types80 db 00000001B ;Mode identifier-Mode 3+ 
colso db 4 ;Color option 

txtc80 dw 80 ;text characters/line 
txtr80 dw 25 ;text lines 

hrs0 aw 720 shorizontal resolution 
vrs0 dw 400 ;vertical resolution 
kbd_buf db 80 ;Keyboard buffer 
lkbd_buf dw $-kbd_buf :Length keyboard buffer 
iowait dw 0 ;Wait for CR 

kbdhdl equ 0 7Keyboard handle 

waitf equ 1 ;Screen waiting status 
dstat db < ;Returned status 
PVBPtri1 label FAR ;Video buffer structure 
bufstl dd OB8000H ;Start physical address 
buflenl dd 4000H ;Buffer length 

physell dw 0 ;0S/2 screen buffer selector 
MASK1 db 01H ;PEL byte mask 

MASK11 dw 0001H ;O0dd/even row mask 
OFFSET1 dw 2000H ;Odd row buffer offset 
four dw 4 

XX daw ig ;PEL modulo parameter 
dummy dw rs 780287 dummy "pop" 

two db 2 

XXX db rs ;Output value 

eighty dw 80 

row dw z ;row 

col dw 2 ;column 

address dw 2 ;Address screen dot 

x dw ? ;Box col parameter 

y dw ? ;Box row parameter 

xb dw 75 ;Start column 

xe dw 150 ;End column 

yb dw 25 ;Start row 

ye dw 175 ;End row 

eight dw 8 

; Data area below is used for screen print routine. 
in_buffer db 320 dup(0) ;print buffer 

bytesin dw 320 :;CGA line 

bytesout dw 0 soutput count 
in_bufferl dab 1BH,4BH,64D,01H ;printer setup 

bytesin1l dw 4 ;count bytes In_bufferl 
in_buffer2 db ODH, OAH ;LF/CR 

bytesin2 dw 2 ;in_buffer2 byte count 
in_buffer3 db 1BH, 41H, 08H 

bytesin3 dw 3 ;in_buffer3 byte count 
in_buffer4 db 1BH, 32H 

’ 

dev_name db 'LPT1',0 ;name of printer device 
dev_hand dw 0 ;device handle 

dev_act dw 0 ; 


Figure 2.7b (Continued) 
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dev_size 0 

dev_attr 0 

dev_flag 00000001b ;Open File 

dev_mode 0000000011000001b shdl private,deny none,w/o 
dev_rsv 0 ;reserved 

N4 ? 

MM 40H,10H,04H,01H ;pel mask 

Ww 128,64,32,16,8,4,2,1 spin weights 

coll 320 dup(?) ;column index-printer 

bl 4 dup(?) 

N ? 

shiftl 6,4,2,0 
s 4 dup(?) ;dup copies pel byte 

ddd ? 

sixforty 640 

scr_buffer 16384 dup(0) ;temporary buffer--screen values 


:printer line 


oO ™e Me te MO tO 


a~ 8 
Q Hog 


=e 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls ;Clear screen 

@VioSetMode CGAm,viohdl ;Set CGA Graphics mode 

call clsCGA :Clear CGA screen 

@VioScrLock waitf,dstat,viohdl ;Lock screen context 
@VioGetPhysBuf PVBPtri1,viohdl ;Get physical buffer selector 
push physell ;Save selector 


pop es ;Load selector into extra segment 


mov ax,0 

mov y,ax 

call lineh ;Draw line 
mov ax,100 


mov y,ax 
call lineh ;d@raw second line 


call scr_ld ;loads the temporory buffer 


@VioScrUnLock viohdl sUnlock screen context 


@KbdStringIn kbd_buf,1lkbd_buf, iowait,kbdhdl shesitate 


@vioSetMode STDm,viohdl ;80 x 25 alpha mode 
call prtscr sprints temporary buffer 
@DosExit action, result ;Terminate process 

ENDP 


ENDS 
END 


Figured 2.7b (Concluded) 


72 


Introductory OS/2 Assembler Programming 
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TITLE GRAPH1 - This program is part of graphlib.1lib(graph1.ASM) 


c1sCGA 


DESCRIPTION: cls,clsCGA,wdor,and lineh routines 


include sysmac.inc 


tr: WORD, 1c: WORD, br: WORD, rc: WORD,no_line:WORD, blank: WORD 
viohdl:WORD, PVBPtri1: FAR, physel1:WORD, waitf:WORD 

dstat: BYTE, four: WORD,col:WORD, xx:WORD, dummy : WORD 

MASK1: BYTE, xxx: BYTE, row: WORD, eighty:WORD, address: WORD 
MASK11:WORD, OFFSET1: WORD, y: WORD, xb: WORD, xe: WORD 

two: WORD 


SEGMENT PARA PUBLIC 'CODE! 
assume cs:cseg 

PUBLIC cls,clsCGA,wdot, lineh 
PROC FAR 


@VioScrollUp tr,1lc,br,rc,no_line,blank,viohdl 
ret 


ENDP 

PROC FAR 

@VioScrLock waitf,dstat,viohdl ;Lock screen context 
@VioGetPhysBuf PVBPtri1,viohdl 


push physell 
pop es 


;Get physical buffer 
;Screen selector 
;Load extra segment 


mov bp,0 
mov al,0O 


;Start offset zero 
;Zero attribute-clear 


mov es: [bpj,al 
inc bp 

cmp bp, 1F3FH 
jle DO1 


;Clear byte 


7;Check end list buffer 


mov bp,2000H 
mov al,0O 


70ffset 2nd buffer-odd 
;Zero attribute-clear 


mov es:[bp],al 
inc b 

cmp bp, 3F3FH 
jle Do2 


7Clear byte 


;Check end 2nd buffer 


@VioScrUnLock viohdl Unlock screen context 


ret 
ENDP 


PROC FAR 
(col,row) = (x,y) 


fild four 
fild col 


;Load stack with 4 
7ST = col, ST(1) = 4 


Figure 2.8 Listing of partial content of GRAPHLIB.LIB. 
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fprem 

fistp xx 
fistp dummy 
mov al,3 

mov bl,byte ptr xx 
sub al,bl 
mov ah,0O 

mul two 

mov cl,al 
mov al,MASK1 
shl al,cl 
mov xxx,al 


MOV ax,row 

shr ax,1 

mov dx,0 

mul eighty 

mov bx,col 

shr bx,1 

shr bx,1 

add ax,bx 

mov address,ax 

mov ax, row 

and ax,MASK11 

cmp ax,0 

jle ELSE1 
mov ax,address 
add ax,OFFSET1 
jmp IF11 


mov ax,address 


mov bp,ax 
mov al,XxXxx 


or es: [bp],al 


ret 
ENDP 


PROC FAR 


y = row position, xb = begin, xe 


MOV ax,Y 
mov row,ax 


mov ax,xb 


mov col,ax 
push ax 
call wdot 
pop ax 

inc ax 

cmp ax, xe 
jle Do10 


ret 
ENDP 


ENDS 
END 


;Modulo 
;Store remainder in xx 
:Pop stack 


7(3 - col % 4) 
;Clear upper multiplicand 


;Shift value for PEL 
*PEL color mask 
;Shift to correct PEL 
;Store buffer value 


e 
‘ 


;Begin address calculation 
;Divide row by 2 

;Clear upper multiplicand 
;Convert column value to bytes 
;offset in ax 

;Save offset base 


:Check even/odd row 
;Look for bit 0 set 


sadd odd buffer offset 


;screen buffer address 
;Attribute value for dot 


;Write dot 


= end 


;Establish row for wdot 


Establish start column 


e 
’ 
e 
’ 


7;Save column value 

;Write dot (col,row) 
;Recall column 

;Increment column 

;Check end horizontal line 


e 
a 


Figure 2.8 (Concluded) 
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2.3.4 Connecting Line Graphics with OS/2 


Consider two disjoint points on the screen at coordinates (x,,y,) and (x,,y,), respec- 
tively. (Assume that x, corresponds to a column value (1,320) and y corresponds to 
a row value [1,200].) If we are plotting a dot at these points, it is desirable perhaps 
to link two points with a line to show connectivity. Since there may exist pixels on 
the screen between these two points, a program could fill in these pixels and the 
screen would appear to have a line connecting the two points. To do this, we use 
the equation for a straight line: 


yY> = Yo + m(x, — Xq) 
Here the slope is 


YN 


m= 
xX, — Xo 


We have used y, and x, as dummy variables to represent the intermediate points in 
question. 

Unfortunately, the density of dots available on the IBM Color Graphics 
Adapter screen is at most 320 x 200 or 640 x 200. Although this seems like a lot 
of points, the screen is large and frequently the connecting lines appear jagged. This 
is because the slope is effectively quantized. To understand this, consider two points 
with slope 0.1 between them. Recognizing that y,, y,, and x, are all integers in 
Equation (2.1), it follows that 


y, =y, + (0.1) (x, - x,) 
Clearly, for y, to increase by one pixel on the screen, x, — x, must change by 11 
pixels in the horizontal direction. Thus the lines appear broken. 

Equations (2.1) and (2.2) are the key to developing techniques for plotting 
connecting line graphics in the IBM microcomputer context (or any other raster 
scanning device, for that matter). Figure 2.9a contains the flowchart for the connect- 
ing line program. Figure 2.9b illustrates the procedure CONNL2, which plots con- 
necting lies between the points (X0,Y0) and (X1,Y1) using as dummy variables 
(X2,Y2). The remaining variables (NCOUNT, SIGN, and M) are self-explanatory. 
The only complex feature of this routine, as it implements Equations (2.1) and (2.2), 
is the scaling mechanism. To prevent undue round-off the numerator of the slope is 
scaled up by a factor of 100. This is subsequently removed. The sign of the slope 
(SIGN) is calculated and used to demarcate the procedure based on positive versus 
negative values. The routine wdot is used to plot the connecting line. 

Figure 2.10 presents a program, slopeln.asm, that plots a connecting line be- 
tween the points | 


(X,; y,.) = (25,25) 
and 


(» y,) = (275,175) 
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PRESERVE 
REGISTERS 
LOAD CONNL2 
DATA SEG. ADD. 


X0 = XSTART 
X1 = XEND 
X2 = XSTART 


YO = YSTART 
Y1 = YEND 
Y2 = YSTART 


GENERATE NUMBER 
"CONNECTING" PTS. 
CALCULATE 
Y1- YO 


Y1- YO 
GREATER 
0? 


Y 
SCALE BY 100: SCALE BY 100: CALCULATE CALCULATE 
M = 100 (Y1 - YO) M = 100 (YO - Y1) YO + M (X2 - XO) YO - M (X2 - XO) 
NEGATIVE POSITIVE WRITE DOT AT 
SLOPE SLOPE X2 AND Y2 
CALCULATE INCREMENT X2 
M (X2- XO) 
DIVIDE BY NUMBER x2> % 
"CONNECTING" PTS. GREATER 


X1? 
N 


RETURN 
REGISTERS 
DIVIDE BY 100 TO DIVIDE BY 100 TO RETURN 
REMOVE SCALING REMOVE SCALING 


Figure 2.9a Functional flowchart for connecting line routine, conn12. 
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TITLE CONNL2- CONNECT LINE AND PLOT (CONNL2.ASM) 


=e %e “se Ve MS Te NO TF 


Le 
s 
eg 


Introductory OS/2 Assembler Programming 


DESCRIPTION:This routine reads DX = 
(YSTART,YEND), BX = XSTART, and CX = XEND. 

It generates a connecting line between the 
points (XSTART,YSTART) and (XEND,YEND) and 
plots the points. The routine as part of the 
S/2 graphlib.lib 


YO:WORD, Y1;: WORD, Y2: WORD, XO: WORD, X1:WORD, X2 : WORD 


NCOUNT: WORD, SIGN: WORD, M: WORD, col: WORD, row: WORD 


wdot: FAR 


Q =e se %e@ Se Se MO Se Te TE “MS Ve YH “NSO Te “WO 


7Y¥-value (dynamic) 

7Y end 

7X start 

;X-value (dynamic) 

7X end 

;Number points in line 
;Sign slope 

;Scaled partial slope 


SEGMENT PARA PUBLIC 'CODE' 


PUBLIC CONNL2 


PROC 


FAR 


ASSUME CS:CLINE 


PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


;Load screen coordinates 
;DH contains YSTART 
;Clear top half AX 
?Start Y-point 

;Also save YSTART in y 
7DL contains YEND 
;Clear top half Ax 
7End Y-point 

;Start X-point 

;Save XSTART in x also 
:End X-point 


Generate count index 


;Larger X-value in increment 
;Calculate X-increment 

zNumber of X-points to connect 
;Generate slope 

;Clear upper numerator register 


:Begin calculation Y1 - YO for slope 


Figure 2.9b Program code for conn12, the connecting line routine. 
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JB ELSE1 
MOV CX,100 
MOV DX,0 
MUL CX 
MOV M,AX 
MOV AX,1 
MOV SIGN,AX 
IMP IIF1 


MOV AX, YO 
SUB AX,Y1 
MOV CX,100 
MOV DX, 0 
MUL CX 

MOV M,AX 
MOV AX,0 
MOV SIGN,AX 


MOV AX, X2 
SUB AX, XO 
MOV DX,0 
MUL M 
DIV NCOUNT 
MOV CX,100 
CMP AX, CX 
JB ELSE2 
MOV 
DIV 
JMP 


MOV 


MOV BX,SIGN 

CMP BX,1 

JB ELSE3 
MOV 
ADD 
JMP 


MOV 
SUB 
MOV 


MOV CX, X2 
MOV Dx, AX 


MOV col,Cx 
MOV row, DX 
CALL wdot 


INC X2 
MOV BX, X2 
CMP BX,X1 
JBE DO1 


CONNL2 


CLINE 
CONNL2 


;Scale slope by 100 
;Clear upper multiplicand register 


;Slope in M 
;Sign negative for slope 
?Sign increment Y-axis points 


;Positive slope 
;Calculate (Y1 - YO) 
7Scale by 100 

7Clear upper register 


?Slope in M 
7Positive slope 
?Sign deecision Y-axis points 


7(X - XO) 
;Clear upper multiplicand register 
*Multiply by slope numerator 
;Begin completion slope calculation 
;Value corresponding to slope 1 
7Check for slope less 1 
;Jump slope less/= 1 
;Clear upper register 
;Remove scaling 


AX,0 70 slope 


;Jump positive slope 


Bx, YO ;Load Y-start value 
AX, BX ;Add Mx(X-X0) 
IIF3 


BX, YO ;Positive slope 
BX, AX ;Generate YO - M x (X - X0) 
AX, BX ;Save in AX 


’ 


7X-position 
7Y-position 


swrite dot 


70S/2 dot routine 


e 
’ 


*Next point 
7Ck X<= X1 


e 
a 


Figure 2.9b (Concluded) 
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TITLE SLOPELN ~- This program plots/prints sloped line (slopeln.asm) 


- 8087 
EXTRN 
IF1 


ENDIF 


Ul 
dgroup 
STACK 


STACK 


DATA 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


; 

PUBLIC 
PUBLIC 
PUBLIC 


me Se Se te te MY we Se te se we 


KKK OM OS OS 
NRFONFO 


DESCRIPTION: This program plots a sloped line in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 


prtscr: FAR, scr_1l1d:FAR,cls: FAR, c1sCGA: FAR, lineh: FAR, connl2: FAR 


include sysmac.inc 


-Ssall ;Suppresses macro lists 
GROUP data 


SEGMENT PARA STACK 'STACK' 
db 256 dup('STACK ') 
ENDS 


SEGMENT PARA PUBLIC 'DATA'‘ 


in_buffer,bytesin,bytesout,in_bufferl,bytesin1 
in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 
s,eight,eighty, four, shift1,scr_buffer 
sixforty,N4,ddd,w,bl 


xx,xXxXx,tr,lc,br,rc,no_line,blank,viohdl, PVBPtr1, physell,waitf 
dstat, four, two,col,dummy,MASK1,MASK11,row,eighty, address 
OFFSET1,y,xb,xe 


7x start 

7x end 

;dummy x 

sy start 

7y end 

;dummy y 

snumber points in line 
;sign slope 

;scaled partial slope 


Figure 2.10 The program slopeln.asm, which plots on the screen a connecting 
line from (row,col) = (25,25) to (175,275). 
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Screen display variables 


viohdl 
result 
action 
tr 

le 

br 

re 
no_line 
blank 
CGAm 
1lmodeE 
typeCGA 
ColCGA 
txtcCGA 
txtrCGA 
hrCGA 
vVrCGA 
STDm 
lmodes0 
types0 
colso 
txtcs0 
txtrso 
hrso 
vrsgo0 


kbd_buf db 


lkbd_buf dw 


iowait dw 


kbdhdl equ 


’ 


waitf equ 


dastat db 


PVBPtri1 label 


bufstl dd 
buflenl dd 
physell dw 


a 

MASK1 db 
MASK11 dw 
OFFSET1 
four 


00000111B 
2 

40 

25 

320 

200 


FAR 

12 
00000001B 
4 

80 

25 

720 

400 


80 
$-kbd_buf 
0 
0 


1 
? 
FAR 


OB8000H 
4000H 


;Required video handle 
;Completion code 
;Terminates current thread 
;Top row screen clear 
:;Left column screen clear 
;Bottom row screen clear 
;Right column screen clear 
;Number lines scrolled 
;Blank character pair 


;Video mode structure-CGA 
;Structure length 

*Mode identifier 

7Color option-Mode 5 

;text characters/line-ignore 
;text lines-ignore 
shorizontal resolution 
;vertical resolution 


;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
:Color option 

stext characters/line 

stext lines 

shorizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
Returned status 


:Video buffer structure 
;Start physical address 
;Buffer length 

70S/2 screen buffer selector 


;PEL byte mask 
;O0dd/even row mask 
7;0ddad row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


;row 
column 
7;Address screen dot 


;Box col parameter 
;Box row parameter 
;Start column 

;End column 

;Start row 

7End row 


Figure 2.10 (Continued) 
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in_buffe 
bytesin 

bytesout 
in_buffe 
bytesinl 
in_buffe 
bytesin2 
in_buffe 
bytesin3 
in_buffe 


dev_name 
dev_hand 
dev_act 

dev_size 
dev_attr 
dev_flag 
dev_mode 
dev_rsv 


shifti 

s 

add 
sixforty 
scr_buff 


eo =e %e MO Me 
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r 
dw 


320 dup(0) 


0 

1BH, 4BH, 64D, 01H 
4 

ODH, OAH 

2 

1BH, 41H, 08H 

3 

1BH, 32H 


rl 
r2 
X3 
r4 


'LPT1',0 
) 

0 

) 

0 
00000001b 


0000000011000001b 


0 


? 
40H, 10H, 04H, 01H 


128,64,32,16,8,4 


320 dup(?) 
4 dup(?) 
° 


6,4,2,0 
4 dup(?) 
? 

640 


er 16384 dup(0) 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 

PROC FAR 

call cls 

@VioSetMode CGAm,viohdl 

call clsCGA 

@VioScrLock waitf,dstat,viohdl 
@VioGetPhysBuf PVBPtr1,viohdl 
push physell 


pop es 


mov 
mov 


dh, 25 
d1,175 
mov bx, 25 
mov cx, 275 
call connl2 


call scr_ld 


tprint buffer 

;CGA line 

;output count 

tprinter setup 

;count bytes In_bufferl 
;LF/CR 

zin_buffer2 byte count 


;in_buffer3 byte count 


sname of printer device 
;device handle 


° 
’ 
e 
’ 
. 
e 
e 
ti 


Open File 

;reserved 

;pel mask 

pega spin weights 
;column index-printer 
;printer line 


;dup copies pel byte 


;temporary buffer--screen values 


;Clear screen 

;Set CGA Graphics mode 

;Clear CGA screen 

;Lock screen context 

;Get physical buffer selector 
;Save selector 

;Load selector into extra segment 
7y-begin 

ry~end 

?x-begin 

7x-end 

splot sloped line 


;loads the temporory buffer 


Figure 2.10 (Continued) 
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;hdl private,deny none,w/o 
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@vioScrUnLock viohdl s;Unlock screen context 


@KbdStringIn kbd_buf,lkbd_buf, iowait, kbdhdl shesitate 


@VioSetMode STDm,viohdl 780 x 25 alpha mode 

call prtscr ;prints temporary buffer 
@DosExit action,result ;Terminate process 

ENDP 


ENDS 
END 


Figure 2.10 (Concluded) 


This program calls conn12 to plot the line on the screen in the usual fashion. Note 
that the assembler is case insensitive. Next the print of the graphics screen is accom- 
plished. The nine variables needed by the connecting line module, conn12, are 
declared public and specified in the data segment of slopeln.asm. Figure 2.11 illus- 
trates the sloped-line output. 


. 

“ee, 
“ee, 

bade) 


*, 
"9, 
Fe, 


*, 
°, 
ee, 
bat? 


Figure 2.11 Screen dump of sloped connecting line from slopeln.asm. 


Figure 2.12 illustrates a procedure bbox1.asm that plots a box based on gen- 
eral parameter inputs: (xb,yb) and (xe,ye) being the opposite corners of the box, 
with the first the upper left side and the second the lower right side. Figure 2.13 is 
the procedure linev, which is the corollary to lineh, and this procedure plots a ver- 
tical line. Figure 2.14 contains the contents of the library module GRAPHLIB.LIB. 
This module has all the graphics primitives and graphics printer screen dump 
modules. 
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PAGE 55,132 
TITLE BBOX1 - This is the boxx module (bbox1l.asm) 


e 
f 


; DESCRIPTION: This module generates a box in protected 
: mode. 


It contains a procedures: boxx 
-8087 


y:WORD, yb: WORD, ye: WORD, x: WORD, xb: WORD, xe: WORD, lineh: FAR 
row:WORD,col:WORD, wdot: FAR, linev: FAR 


SEGMENT PARA PUBLIC 
assume cs:cseg 
PUBLIC boxx 


"CODE! 


PROC FAR 


xb = x-begin,xe = x-end,yb = y-begin,ye = y-end 


mov ax,yb 
mov y,ax 
call lineh 
mov ax,ye 
mov y,ax 


7Top box line 


;Draw top horizontal line 
;Bottom box line 
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call lineh 
mov ax,xb 
mov x,ax 
call linev 
mov ax,xe 
mov x,ax 
call linev 


ret 
ENDP 


ENDS 
END 


;Draw bottom horizontal line 
s;Left box line 


:Draw left vertical line 
:Right box line 


;Draw right vertical line 


Figure 2.12 Routine bboxl.asm, which plots box and contains procedure boxx. 


Finally, Figure 2.15 illustrates a program that exercises boxx, the procedure for 
plotting a box based on the module bbox1l.asm. This program is called bbox.asm 
and links as follows: 


[ez\)] 


IBM Linker/2 
Copyright(c) 
Copyright(c) 


Run File 


Libraries 


link bbox 


Version 1.00 
IBM Corporation 1987 
Microsoft Corp 1983-1987. 


All rights reserved. 


[BBOX. EXE]: 
List Files 


(NUL.MAP) : 


[ LIB]: 
Definitions File 


doscalls + graphlib 
[NUL.DEF]: 
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TITLE LLINEV - This is the linev module (llinev.asm) 


r 
, 
e 
‘ 
ry 
’ 
e 
, 
° 
’ 
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DESCRIPTION: This module generates a vertical line in protected 
- It contains a procedure: linev 


mode 


y: WORD, yb: WORD, ye: WORD, x:WORD, xb: WORD, xe: WORD 
row: WORD, col: WORD, wdot: FAR 


SEGMENT PARA PUBLIC 
assume cs:cseg 
PUBLIC linev 


PROC 


push 
call 
PoP 
inc 
cmp 
jle 


ret 
ENDP 


ENDS 
END 


FAR 


col position, yb = begin, ye 


ax,X 
col,ax 


ax,yb 


row,ax 
ax 
wdot 

ax 

ax 

ax,ye 

Dpo20 


*CODE' 


= end 


sEstablish column for wdot 


:Establish start row 


7;Save row value 
;Write dot (col,row) 
7Recall row 
s;Increment row 
;Check end vertical line 


. 
, 


Figure 2.13 Vertical line procedure, linev. 


BOXXX... eee eee eee e sDDOX] 
CLSCGA.......++---graphl 
LINEV....-eeeeeeeelLLinev 
SCR_LD............scrld 


scrld 


SCR_LD 


prtscr 


PRTSCR 


bbox1 
BOXX 


llinev 
LINEV 


graphi 
CLS 


Offset: 


Offset: 


Offset: 


Offset: 


offset: 


CLSCGA 


00000010H 


000000a0H 


000006b0H 


000007b0H 


00000870H 


CLS. ccccccccccese  Graphl 
LINEH.....++.+ee---Qraphl 
PRTSCR....+ee+-----prtscr 
WDOT...0e2-e22056562--graphl 


Code 


Code 


Code 


Code 


Code 


and data size: 
and data size: 
and data size: 
and data 


and data size: 


LINEH 


29H 


233H 


2dH 


1bH 


104H 
WDOT 


Figure 2.14 Listing of GRAPHLIB.LIB, illustrating the screen graphics and 


screen print routines. 
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132 


TITLE BBOX - This program plots/prints a box using modules (bbox.asm) 


=e 76 Se Se TO 


=e te Me MO NO 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


e 
’ 
° 
’ 
° 
a 
° 
’ 
° 
‘ 


PUBLIC 
PUBLIC 
PUBLIC 


e ™e Me tO Ne we 


viohdl 
result 
action 
tr 

le 

br 

re 
no_line 
blank 


CGAm : 
lmodeE 
typeCGA 
colCGA 
txtcCGA 
txtrCGA 
hrCGA 
vrCGA 


Figure 2.15 


DESCRIPTION: This program plots a box in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 


prtscr:FAR,scr_1d:FAR,cls: FAR,c1sSCGA: FAR, boxx: FAR 


include sysmac.inc 


-sall ;Suppresses macro lists 
GROUP data 


SEGMENT PARA STACK 'STACK'! 
db 256 dup('STACK *) 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 


in_buffer,bytesin,bytesout,in_bufferl,bytesinl 
in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 
s,eight,eighty,four,shiftl1,scr_buffer 
sixforty,N4,ddd,w,b1 


xX,Xxx,tr,lc,br,rc,no_line,blank,viohdl, PVBPtr1, physell,waitf 
dstat, four, two,col,dummy,MASK1,MASK11,row,eighty,address 
OFFSET1,y,xb,xe,x,yb,ye 


;Required video handle 
;Completion code 
;Terminates current thread 
;Top row screen clear 
Left column screen clear 
;Bottom row screen clear 
;Right column screen clear 
sNumber lines scrolled 
;Blank character pair 


;Video mode structure-CGA 
;Structure length 

00000111B ;Mode identifier 
;Color option-Mode 5 
;text characters/line-ignore 
;text lines-ignore 
shorizontal resolution 
;vertical resolution 


Program that graphs box on screen and then dumps output to printer. 
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e 

STDm label 

lmode8s0 dw 

type8s0 db 00000001B 
colso dab 4 

txtc80 dw 80 

txtr8s0 dw 25 

hr8s0 dw 720 

vr8s0 dw 


kbd_buf db 
lkbd_buf dw 
iowait dw 
kbdhdl equ 


‘ 
waitf equ 
dstat dab 


PVBPtr1 label FAR 
bufst1 dd OB8000H 
buflenl dd 4000H 
physell dw 0 


MASK1 ab 01H 
MASK11 dw 0001H 
OFFSET1 dw 2000H 
four aw 
XxX 

dummy 

two 

XXX 

eighty 

row 

col 
address 


VV OVD Vo 


~e MO MO Ne TO Te 


in_buffer 
bytesin dw 
bytesout 0 

in_bufferl 1BH, 4BH, 64D, 01H 
bytesin1 4 

in_buffer2 ODH, OAH 
bytesin2 2 

in_buffer3 1BH, 41H,08H 
bytesin3 3 

in_buffer4 1BH, 32H 


320 dup(0) 


’ 
dev_name 
dev_hand 
dev_act 
dev_size 
dev_attr 


"LPT1',0 
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;Video mode structure-80x25 
;Structure length 

:;Mode identifier-Mode 3+ 
:Color option 

stext characters/line 

stext lines 

shorizontal resolution 
ivertical resolution 


:Keyboard buffer 
Length keyboard buffer 
;Wait for CR 

:Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

70S/2 screen buffer selector 


;PEL byte mask 
;O0dd/even row mask 
;O0dd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


7row 
;column 
sAddress screen dot 


;Box col parameter 
;Box row parameter 
;Start column 

7End column 

;Start row 

;End row 


;print buffer 

;CGA line 

;output count 

sprinter setup 

;count bytes In_bufferl 
;LF/CR 

;in_buffer2 byte count 


;in_buffer3 byte count 


sname of printer device 
;device handle 


Figure 2.15 (Continued) 
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dev_flag 
dev_mode. 
dev_rsv 


00000001b 


0 


5 


40H,10H,04H,01H ;pel mask 
128,64,32,16,8 
320 dup(?) 

4 dup(?) 

> 


6,4,2,0 

4 dup(?) 

? 

640 

16384 dup(0) 


sixforty 
scr_buffer 


we 0 we ~o se we Se 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 

PROC FAR 

call cls 

@vioSetMode CGAm,viohdl 

call clsCGA 

@vioScrLock waitf,dstat,viohdl 
@vioGetPhysBuf PVBPtri1,viohdl 
push physeli 
pop es 

call boxx 
call scr_ld 
@vioScrUnLock viohdl 
@KbdStringIn kbd_buf,1lkbd_buf, 
@vioSetMode STDm,viohdl 

call prtscr 

@DosExit action,result 

ENDP 


ENDS 


END oS21 


0000000011000001b 
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;Open File 
shdl private,deny none,w/o 
;reserved 


74,2,1 ;pin weights 
;column index-printer 


;printer line 


:dup copies pel byte 


;temporary buffer--screen values 


;Clear screen 
;Set CGA Graphics mode 
;Clear CGA screen 
;Lock screen context 
7Get physical buffer selector 
;Save selector 
;Load selector into extra segment 
;generate box 
sloads the temporory buffer 
;Unlock screen context 
iowait, kbdhdl shesitate 
780 x 25 alpha mode 


;prints temporary buffer 


;Terminate process 


Figure 2.15 (Concluded) 
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Figure 2.16 presents the output for the box. It assumes the following corner values 


based on the data segment specification: 
(xb, yb) = 
and 


(75,25) 


(xe, ye) = (150,175) 
It is important to recognize that the method for accessing the OS/2 physical 
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display buffer is initially cumbersome since the display context must first be locked. 
Good programming practice, however, would implement this step only once during 
execution of a given process or thread. Then full-screen DMA is permitted. Al- 
though the advantage of using multitasked display contexts under OS/2, for example, 
is lost, the programmer still has access to the very large address space provided by 
OS/2. 


OA doreUEOseE Re COEOOL meet Sosawenes t boEeender Omen HeCErenee HmOS D 


Figure 2.16 Box screen print from 
bbox.asm (Figure 2.15). 
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It is the benefits of multitasking and memory access that highlight OS/2’s 
attributes. If animation or rapid update of the screen context is needed, the applica- 
tion must be structured to maximize its screen access while continuing to take 
advantage of other task-sharing arrangements and memory requirements in a multi- 
tasking environment. 


2.4 SOFTWARE DESIGN 


No introductory programming discussion would be complete without mentioning 
software design techniques. Three principals come to mind: 


1. Modular code 
2. Top-down design 
3. Structured programming 


These form the foundation for developing optimized computer programs [6,7]. 

We have seen examples of the use of modular code in the examples presented 
so far. Basically, programs have been developed on existing independent smaller 
modules (such as prtscr, bbox, lineh, linev, ...).These modules may be linked as 
separately assembled (in this case) routines or appear in libraries. The entire notion 
of the API embodies a modular approach to handling system services. 

Top-down design is somewhat straightforward and starts with a high-level 
statement of the problem to be solved. From this approach a flowchart can be 
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developed or, alternatively, a written language rendition of what the program will 
accomplish. These two approaches lead naturally into program development. It is not 
the intention of this book to teach design fundamentals; hence we will usually 
confine ourselves to the actual code implemented in each instance. It is assumed that 
the reader can generate design artifacts in either flowchart format or pseudo-code. 
General guidelines tend to suggest flowcharts when program dynamics are particu- 
larly important. As size becomes a factor, the interfaces tend to dominate program- 
ming considerations and pseudo-code becomes desirable. 

Finally, we mentioned structured programming. Assembler is intrinsically 
unstructured because of the conditional and unconditional jump instructions. Guide- 
lines exist, however, that permit structured techniques with assembly language and 
very understandable code results [8,9]. As Martin points out (reference 6), an excel- 
lent starting point for top-down design is the development of a structure chart that 
links each module in static fashion. Structured code accomplishes similar design 
tasks by forcing the designer to limit access to each module. Parameter passing be- 
comes very orderly and the variables used within a module are maintained locally 
except for those passed externally. The flow of execution is orderly and downward 
avoiding unrestrained jumps within the code. In BASIC ‘and C, for example, the 
goto instruction is avoided. Entry points are accessed in traceable fashion. We will 
discuss C programming in a subsequent chapter, and the syntax of the language 
naturally lends itself to structured code. In assembly language the use of syntax of 
the form 


cmp ax,parm 
jle ELSE1 


jmp IIF1 


implements the familiar IF. ..THEN...ELSE... structure. Note the use of uncondi- 
tional jumps to do this. The reader must, of course, recognize that any decision logic 
in a higher-level language results in conditional or unconditional jumps at the assem- 
bler or machine code level. The fact that we can structure such an assembler, how- 
ever, yields significant improvement in clarity and understanding. 


2.5 SUMMARY 


The goal of this chapter was to introduce assembler programming for OS/2 with a 
particular emphasis on the techniques needed to access the Application Program 
Interface. It was the use API services, as demonstrated through specific examples, 
that we intended to emphasize. We developed examples of printer and display ac- 
cess within the API context. A set of program modules was written that allow the 
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user to obtain a screen dump for the CGA graphics screen. This is similar to the fa- 
miliar DOS GRAPHICS.COM routine except that they are not terminate and stay 
resident (TSR) programs but must be called as active program modules. Similarly, 
they must be linked to the user program either as stand-alone modules or from the 
library GRAPHLIB.LIB established in the chapter. 

It is clear from the chapter that the API must be accessed in more structured 
fashion than the normal interrupt call, where free access to the general-purpose 
registers is permitted. The advantages of accessing memory above 1 MB are pro- 
vided by OS/2, and the API architecture is a consequence of this process. Also, the 
features of multitasking require a Protected Mode structure. Hence these two aspects 
of programming with Intel hardware such as the 80286 cause programming struc- 
tures such as the API to become essential. This, then, is the justification for learn- 

ing the API and using OS/2. Eventually, when the programming applications reach 

a size where only OS/2 can offer the memory allocation or severe multitasking 
constraints are placed on the user, DOS will inevitably be replaced by OS/2. Thus 
the programming techniques of this chapter are the beginning approaches to learn- 
ing how to manage IBM’s next-generation microcomputer operating system. 
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PROBLEMS 


2.1 Output of a character in the printer graphics mode causes the pins in the print head to 
fire, depending on the value of the character (0-255). Which pins fire for the Epson 


90 


2.2 


Leo 


2.4 


20 
2.6 


2.4 


2.8 
2.9 
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FX-85 for the following values: (a) 174; (b) 203; (c) 85? Assume that the top pin 
is number 8. 


The macro call 


@VioGetPhysBuf PVBPrt1,rsv 


is an example of the OS/2 access to the physical buffer selector (contained in the 
structure PVBPrt1). If the calling sequence for VIOGETPHYSBUF, the API routine, is 
given by 


EXTRN VioGetPhysBuf:FAR 


PUSH@ Label Data structure (PVBPrtl1) 
PUSH word reserved 
CALL VIOGETPHYSBUF 


write a macro to achieve the call indicated above. Use the macros defined in the chap- 
ter: @define, @pushw, and @pushs. 


As in Problem 2.2, if the macro @VioScrLock has the calling sequence 


EXTRN VioScrLock:FAR 


PUSH word waitflag 
PUSH@ BYTE status 
PUSH word handle 


CALL VIOSCRLOCK 


define a macro to achieve the call using the macros defined in the chapter: @define, 
@pushw, and @pushs. 

The EGA graphics on the IBM Monochrome Display is a 640 x 350 graphics mode 
(ModeHexF). The first eight pixels on the screen are defined by the contents of 
memory in location AOOOOH. The screen buffer is mapped into two planes (Map0 and 
Map2). Assume that only Map0 is specified (a default value of white on the normal 
background) and this subtends the first 28,000 bytes at AOQOOOH. If each bit corre- 
sponds to O (black) or 1(white), what changes would be needed to the programs in 
this chapter to allow the code to properly access the EGA screen buffer? 

Write a code fragment that generates the note C (5000 Hz) for 1 second. 


Write a code fragment that plots a straight line from (row, col) = (25,75) to (165,235). 
Use conn12. 


Write a code fragment that beeps the speaker for 5 seconds (1000 Hz) following the 
striking of a key on the keyboard. 

Is it possible to program OS/2 using simply the OS/2 supplied by IBM? Explain. 
When accessing the physical screen buffer, a segment selector was obtained using 
VioGetPhysBuf. This selector was pushed and popped into es, the extra segment regis- 


ter. Screen buffer address locations were then accessed using, for example, a segment 
override: 


es: [bp] 
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2.10 


2.11 


100 


2.12 


213 


2.14 


pA Be 


where bp was the offset in the screen buffer. What key assumption permits this ad- 
dressing scheme, and how is it implemented? 

Structure labels used by the API Toolkit services represent FAR or NEAR loca- 
tions? Why? 

A structure chart lays out the hierarchy of control for a program. Consider a struc- 
ture chart that calculates a Gaussian random array and plots it on the screen. What 
deficiency exists in this presentation assuming that the functional characteristics of 
each block are accurate and complete? 


000 


PLOT RANDOM 
ARRAY 


200 


INPUT GENERATE 
SEED ARRAY 


220 230 


210 


SET GENERATE PRODUCE SCREEN 


RANDOM GAUSSIAN PRESENTATION 


NUMBER 
SCALING 


In ordinary printing the line spacing is 1/6 inch. The command 
ESC A (n) 


produces a line spacing of n/72 of an inch. What command is needed in prtscr to 
return the printer to normal spacing? 

A key aspect of OS/2 programming is that the device driver Interrupt Service Rou- 
tine (ISR) is the only type of program authorized to receive hardware interrupts. 
Each device driver can have an ISR to process the device interrupts. When the in- 
terrupt routine is given control, it has access to the GDT but not any specific LDT. 
The routines must rely on the DevHIp services to access application buffers. These 
routines run at the highest level of the kernel mode. Are they preemptable by OS/2 
task switches? Explain. 


Explain why scr_ld must be called with the screen locked and why prtscr should not 
be called with the screen locked. 


When drawing a line segment from 
(row,column) = (10,10) 
to 


(row,column) = (20,110) 
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how many small straight-line raster segments will be visible in the actual plotted 
line? 

2.16 DosExitCritSec executes after DosEnterCritSec and reenables thread switching for 
the current process. A count of the number of outstanding DosEnterCritSec requests 
is maintained. When are these functions likely to be used? 


2.17 Observe that DosExit is used only at the conclusion of the main calling module. 
What are the criteria for this exit, and how should other modules be terminated? 


Ks Memory Management 
and Multitasking 
with Assembler 


OS/2 is first and foremost a multitasking and memory management operating sys- 
tem. It was developed around the Intel 80286 Protected Mode hardware implemen- 
tation and employs the features of this hardware, such as segment selector protection 
mechanisms, to achieve multitasking operation. The goal of this chapter is to ac- 
quaint the reader with these features of OS/2 in an assembler programming environ- 
ment. 


3.1 MEMORY MANAGEMENT AND MULTITASKING 


Memory management and multitasking represent siatic and dynamic aspects of 
programming and are intimately tied to the protection mechanisms of the 80286 for 
the OS/2 environment. The 80286 has three basic protection aspects: 


1. Isolation of system software from end-user applications 
2. Isolation of users from each other 
3. Data-type checking 


In terms of a ringed picture, the 80286 provides a four-level increasingly privileged 
protection mechanism that isolates applications from the various layers of system 
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software. To understand protection on the 80286, we must begin with its basic parts: 
segments and tasks. It is interesting that this division leads naturally into memory 
management and multitasking. Both are interrelated as pointed out above and yield 
a full Protected Mode picture. 

The following illustrates a complete 80286, descriptor cache register (as we 
have seen in Chapter 1): 


Selectors 


Segment Register Access Segment Base Segment Size 
Rights Address 


Program Visible | Program Invisible 
(loaded by program) (loaded by CPU) 


The important features of this register that should be recognized are that in the 
invisible portion of the register both the access rights byte (with segment type and 
privilege level) and size are used to determine protection priority and the segment 
base address confirms that the selected segment is valid. Hence a hardware imple- 
mentation is used to restrict segment access. 

By way of review, dynamically each task consists of up to four active seg- 
ments (with segment registers CS, SS, DS, and ES), as we have seen. The method- 
ology above is used to control segment protection, and since the hardware can 
dynamically check protection data, this extends into the task realm. The protection 
data are used at two different times dynamically: upon loading a segment register 
and upon each reference to the selected segment. Each task can address up to a gi- 
gabyte (2-2 segments of up to 65,536 bytes) of virtual memory defined by the 
task’s LDT and the system GDT. The task’s private address space (LDT) can oc- 
cupy up to one-half this memory. The rest is defined by the GDT. The CPU has a 
set of base and limit registers that point to the GDT and the LDT of the currently 
running task. These registers exist for CS, SS, DS, and ES as defined for the task. 
An active task can only load selectors that reference segments defined by its LDT 
descriptors or the GDT. Since a task cannot reference descriptors in other LDTs, 
protection violations cannot occur. 

All descriptor tables have a limit used by the protection hardware to ensure 
that correct address space size allocation occurs. This ensures that separation of tasks 
takes place. The third ingredient in this protection mechanism is the implementation 
of privilege-level checks based on the access rights byte assigned privilege level. 
The 80286 privilege-levels are: 


1. Level 0: The kernel (most trusted) includes memory management, task isola- 
tion, multitasking, intertask communication, and I/O resource control. 


2. Level 1: System Services (next most trusted level) provides high-level func- 
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tions such as file access scheduling, character I/O, data communications, and 
resource allocation. 


3. Level 2: Custom Extensions (third most trusted level) allows standard sys 
tem software to be customized: database managers, logical file access services, 
and so on. 


4. Level 3: Applications (least trusted) include normal programming environ- 
ment. 


It is important to recognize the protection intrinsic to this hierarchy. Functions 
catastrophic to system failure are more tightly protected. This ensures that tasking 
can continue to execute in the event of single-task failures. Descriptor privilege, 
including code segment privilege, is assigned when the descriptor is created. The 
system designer assigns privilege directly when the system is constructed or indi- 
rectly using a loader. This is how OS/2 functions. OS/2 was designed with appro- 
priate access byte values associated with the kernel and each system service seg- 
ment. The linker (and loader) assign privilege at a higher level (less trusted) to all 
applications software subsequently developed. The programmer does not normally 
have access to this privilege specification, and we will not tamper with this mecha- 
nism. These are, however, the techniques used by OS/2 to provide memory manage- 
ment and multitasking protection (segment base checking, limit checks, and access 
rights byte validation). 

Task privilege is dynamic and can change only when control transfers from 
one code segment to another. Descriptor privilege, including code segment privilege, 
is assigned when the descriptor is created. Clearly, as a task executes, the privilege 
level of the task must correspond to that of the code segment currently executing. 
Hence such privilege is dynamic. Several general rules apply: 


1. Data access is restricted to those segments whose privilege level is the same 
or less privileged (numerically greater) than the current privilege level (CPL). 


2. Direct code access is restricted to code segments of equal privilege. 
3. A gate is required for access to code at more privileged levels. 


A gate is a control descriptor consisting of four words. It is used to redirect execu- 
tion to a different segment at a more privileged level. These call gate descriptors are 
used by control instructions (call and jump instructions) in much the same fashion 
as segment descriptors are used during normal transfer of code segments at the same 
level. 

Above, we have briefly examined the background for memory management 
and multitasking. Here the emphasis has been on hardware features and privileged 
access (and summarizes the discussion of protection in Chapter 1). It is important 
to recognize that these are hardware features in the Intel chips. Multitasking and 
dynamic memory allocation are particularly well suited to the Intel segmented 
- memory [1]. CPUs with less protection, such as simple system and user privilege, 
are less ideally suited for protection during multitasking [2]. 
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3.2 MEMORY MANAGEMENT ACTIVITIES 


This section is intended to illustrate simple programming concepts related to 
memory management. Under OS/2 the management of memory is accomplished 
dynamically using the API calls. These calls all execute primarily at level 0 and 
permit memory management of higher-level code, such as applications developed by 
the user. 


3.2.1 Creating and Accessing Memory Segments 


The simplest activity associated with memory management is the creation, access, 
and destruction of a memory segment. The code associated with accomplishing this 
action is represented as follows: 


msize dw (size in bytes of segment) 
msell dw ? 
mflag dw 0000000000000111B ;sharable, discardable 


@DosAllocSeg msize, msell, mflag 


@DosFreeSeg mselil 


Figure 3.1 illustrates the program twolnm.asm, a modified version of the 
module twoln.asm. This program creates a temporary buffer in place of scr_buffer 
(the buffer used earlier) and uses the representative code shown above to accom- 
plish this action. The parameter msize has been specified to be 16,384 bytes, the 
buffer size for the screen buffer. A selector, msell, is obtained from the call to 
@DosAllocSeg, and the specified flag indicates that the selector’s segment is shar- 
able among code segments other than the one creating the segment, and may be dis- 
carded. Finally, once the print screen function is performed, the segment is discarded 
using the @DosFreeSeg call. | 

Figure 3.2 contains the code for scr_Idm, a modified version of scr_Id. Since 
the physical screen buffer segment must be accessed using ES (based on selector 
physel1) and the newly created temporary buffer (using the selector msel1), the extra 
segment must share its usage between these two selected segments. To accomplish 
this, es is pushed after each reference to the physical screen buffer, loaded with 
msel1, and then used to access the temporary buffer. Following this action, the 
physical screen buffer is popped back into es and another access of this buffer 
accomplished. Intermediate buffer values are passed using AX. (Note: We use upper 
and lowercase references to the 80286 registers in interchangeable fashion.) 

Figure 3.3 provides the program for the module prtscrm, a modified version of 
prtscr. The only change in this routine is the earlier access to scr_buffer: 
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PAGE 55,132 
TITLE TWOLNM - This program plots/prints 2 lines (twolnm.asm) 


=e we we we Ye 4% 


e =e Se “08 Se 


’ 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


e %e Yeo Ve we 


e@ 30 Ne Ne te Se Ht Ne we 


viohdl 


result 
action 


tr 
lc 
br 
re 


no_line 


blank 
; 

CGAm 
lmodeE 


DESCRIPTION: This program plots two lines in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 

The routine uses DYNAMIC MEMORY ALLOCATION. 


prtscrm: FAR, scr_ldm:FAR,cls: FAR, Cc1SCGA: FAR, lineh: FAR 


include sysmac.inc 


-sall ;Suppresses macro lists 
GROUP data 


SEGMENT PARA STACK ‘STACK! 
db 256 dup('STACK ‘') 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 


in_buffer,bytesin,bytesout,in_bufferl,bytesin1 
in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 

s,eight,eighty, four,shiftl 

sixforty,N4,ddd,w,b1 


xX,xXxx,tr,lc,br,rc,no_line,blank,viohdl, PVBPtr1,physell,waitf 
dstat, four, two,col,dummy, MASK1,MASK11, row, eighty, address 
OFFSET1,y,xb,xe 


;Required video handle 
;Completion code 
:Terminates current thread 
;Top row screen clear 
;Left column screen clear 
;Bottom row screen clear 
;Right column screen clear 
;Number lines scrolled 
;Blank character pair 


;Video mode structure-CGA 
;Structure length 


typeCGA db 00000111B *Mode identifier 


Figure 3.1 The program twolnm.asm (a modified version of twoln.asm), which 
creates a buffer for the screen memory. 
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colCGA db 
txtcCGA dw 
CxtrcGA dw 
hrcGA dw 
vrcCGA dw 
SsTDm label 
lmodes0 dw 
types80 db 
col18s0 ab 
txtc80 dw 
txtr8s0 dw 
hr8s0 aw 
vr8s0 aw 


kbd_buf db 
lkbd_buf dw 
iowait dw 
kbdhdl 
waitf 

dastat 


PVBPtr1 
bufst1 

bufleni 
physell 


a 
MASK1 
MASK11 
OFFSET1 
four 

XxX 
dummy 
two 

XXX 
eighty 
row 

col 
address 


eo *~e Se %O MO Ne 


in_buffer 
bytesin dw 
bytesout 
in_bufferl 
bytesin1l 
in_buffer2 
bytesin2 
in_buffer3 
bytesin3 
in_buffer4 


2 
40 
25 
320 
200 


FAR 
12 


00000001B 


4 
80 
25 


FAR 
OB8000H 
4000H 

0 


01H 
0001H 
2000H 


Vv OVN Vv & 


320 dup(0) 


0 


1BH, 4BH, 64D, 01H 


4 
ODH, OAH 
2 


1BH, 41H, 08H 


3 
1BH, 32H 


;Color option-Mode 5 

ztext characters/line-ignore 
;text lines-ignore 
shorizontal resolution 
;vertical resolution 


;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

stext lines 

shorizontal resolution 
svertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

70S/2 screen buffer selector 


;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy “pop" 


;Output value 


7row 
;column 
s;Address screen dot 


;Box col parameter 
;Box row parameter 
*Start column 

7End column 

;Start row 


sprint buffer 

7CGA line 

;output count 

?printer setup 

;count bytes In_bufferl 
;LF/CR 

;in_buffer2 byte count 


;in_buffer3 byte count 


Figure 3.1 (Continued) 
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dev_name 
dev_hand 
dev_act 

dev_size 
dev_attr 
dev_flag 
dev_mode 
dev_rsv 0 


00000001b 


2 
40H,10H,04H,01H ;pel mask 
128,64,32,16,8,4,2,1 
320 dup(?) 
4 dup(?) 

? 


shiftl 6,4,2,0 
s 4 dup(?) 
ddd ? 
sixforty 


0000000000000111B 


SEGMENT PARA PUBLIC 'CODE! 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls 
@vioSetMode CGAm,viohdl 


call cl1sCGA 


@vioScrLock waitf,dstat,viohdl 


@VioGetPhysBuf PVBPtri1,viohdl 
push physell 
pop es 


mov ax,0 
mov y,ax 
call lineh 
mov ax,100 
mov y,ax 
call lineh 


@DosAllocSeg msize,msell,mflag 
call scr_ldm 


@VioScrUnLock viohdl 


@KbdStringIn kbd_buf,1lkbd_buf, iowait,kbdhdl 


@vVioSetMode STDm,viohdl 


call prtscrm 
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0000000011000001b 


99 


;name of printer device 
;device handle 


;Open File 
shdl private,deny none,w/o 
;reserved 


;pin weights 
;column index-printer 


sprinter line 


;dup copies pel byte 


;temporary buffer-screen values 
zallocated selector 
;segment sharable, discardable 


;Clear screen 
;Set CGA Graphics mode 


;Clear CGA screen 
;Lock screen context 
7Get physical buffer selector 


7Save selector 
;Load selector into extra segment 


;Draw line 


sdraw second line 

sallocate temporary buffer 
sloads the temporory buffer 
;Unlock screen context 
shesitate 
780 x 25 alpha mode 


;prints temporary buffer 


Figure 3.1 (Continued) 
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@DosFreeSeg msell ;free allocated space 


@DosExit action, result ;Terminate process 


ENDP 
ENDS 
END OS21 


Figure 3.1 (Concluded) 
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TITLE SCRLDM -- This routine loads the screen print buffer (scrldm.asm) 


DESCRIPTION: This routine accompanies prtscr to load 

and print the screen in 320 x 200 mode. 

The prtscr buffers are assumed loaded. This is an OS/2 

routine. This routine uses DYNAMIC MEMORY ALLOCATION through msell. 


msel1:WORD 


me EEf we we me we we ws 


-sall 


SEGMENT PARA PUBLIC 'CODE' 
PUBLIC scr_ldm 

PROC FAR 

ASSUME CS:CSEG 


e 
f 


mov cx,100 7no. of raster pairs 
mov di,0O sindex to screen buffer 
mov si,0O ;index to dummy array 


push cx 
mov cx,80 ;raster row length 


mov al,es: {di} sload even row physical buffer 
mov ah,es: [di+2000H] ;odd row physical buffer 


push es 

mov es,mselil 

mov es:[si),al ;load even rows 
mov es:[(si+80j,ah ;0odd rows 

pop es 


inc si 
inc di 
loop DO56 


r 
c 
° 
‘ 


adda si,80 
pop cx 
loop DO55 


skip to next double set 


ret 
ENDP 
ENDS 
END 


Figure 3.2 The modified scrld.asm (scridm.asm) used with the program 
wolnm.asm. 
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55,132 
prtscrm - print screen (prtscrm.asm) 


DESCRIPTION: This routine prints the screen in 
320 x 200 CGA mode. This routine uses DYNAMIC 
MEMORY ALLOCATION. This routine needs the 
following data items in the calling routine 
data segment: 


in_buffer 320 dup(0) 
bytesin 320 

bytesout 0 

in_buffer1 1BH, 4BH, 64D, 01H 
bytesinl 4 

in_buffer2 ODH, OAH 
bytesin2 2 

in_buffer3 1BH, 41H, 08H 
bytesin3 3 

in_buffer4 1BH, 32H 


dev_name 'LPT1',0 

dev_hand 0 

dev_act 0 

dev_size fy) 

dev_attr 0 

dev_flag 00000001b 

dev_mode 0000000011000001b 
dev_rsv dd 

MM 40H, 10H, 04H, 01H 

w 128,64,32,16,8,4,2,1 
coll 320 dup(?) 

N ? 

N4 

s 
shift1 
eight 
eighty 
bl 


> 2 


= 


four 
ddd 
sixforty 


Avhl & WOO OO ov = 


« 
e 
e 
’ 
e 
, 
. 
’ 
° 
’ 
e 
e 
e 
’ 
e 
’ 
e 
’ 
e 
e 
Y 
e 
° 
’ 
e 
a’ 
° 
e 
e 
v 
e 
’ 
e 
’ 
e 
? 
e 
’ 
e 
¢ 
e 
e 
e 
¢ 
e 
° 
e 
, 
e 
s 
e 
7 
e 
e 
e 
’ 
e 
e 
e 
’ 
e 
‘ 
e 
’ 
e 
’ 
e 
’ 
° 
’ 
e 
’ 
° 
’ 
e 
s 
° 
’ 
e 
’ 
° 
, 
e 
e 
° 


MM: BYTE, w: BYTE, col1: BYTE 

in_buffer: BYTE, in_buffer1:BYTE,in_buffer2: BYTE 
in_buffer3: BYTE, in_buffer4: BYTE 

bytesin: WORD, bytesin1:WORD, bytesin2:WORD, bytesin3: WORD 
bytesout: WORD, dev_name: BYTE, dev_hand: WORD 
dev_act:WORD, dev_size:DWORD,dev_attr:WORD 
dev_flag:WORD, dev_mode: WORD, dev_rsv: DWORD 

N: WORD, N4: WORD 
eighty:WORD,eight:WORD, four:WORD,s: BYTE, shift1: BYTE 
ddd:WORD,b1: BYTE, sixforty:WORD,msel1:WORD 


include sysmac.inc 


-sall 


SEGMENT PARA PUBLIC 'CODE' 
PUBLIC prtscrm 


Figure 3.3. The modified prtscr.asm (prtscm.asm) used with the program 
twolnm.asm. 
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prtscrm PROC 
ASSUME CS:CSEG 


FAR 


;open device 


Chap. 3 


@DosOpen dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag,dev_mode,dev_rsv 
cmp ax,0 


=e %6¢ “Se te te 


je E 


r 


LSE1 


et 


;Exit 


sinitialize device 


@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 
@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 


mov 
mov 


push 
push 
mov 
mul 


ax,25 
si,0O 


ax 

si 
ax,si 
sixforty 


mov N,ax 


call 


mov 
mov 


mov 
mov 
mov 
mov 
mov 
mov 
mov 
mov 
add 
loop 


ldarray 


di,o0 
cx, 80 


al,coll[di] 
in_buffer[di],al 
al,coli[dit+1] 
in_buffer[di+1],al 
al,col1[di+2] 
in_buffer(di+2],al 
al,coll[{di+3] 
in_buffer([di+3],al 
di, four 

LOOP2 


v 


;number print lines (+1) 
s;index to 8 row block 


;preserve dx 


;preserve block count 


7640 block size 
:Save in N 


e 
s 


e 
’ 


;initialize 320 column counter 
;count of column bytes 


:column 1 from byte 
;load print buffer 
;column 2 from byte 
;load print buffer 
;column 3 from byte 
;load print buffer 
scolumn 4 from byte 
zload print buffer 


s;increment column index 


;write print row 


@DosWrite dev_hand,in_bufferl1,bytesin1,bytesout 
@DosWrite dev_hand,in_buffer,bytesin, bytesout 
@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 


pop 
pop 
dec 
inc 
cmp 
jle 
3 
@Dos 
ret 
endp 


PROC 


si 

ax 

ax 

si 

ax,0 
DII1 

mp LOOP1 


Close dev_hand 


NEAR 


s 


srecall block count 


;recall print line count 


s;decrement count 


sincrease block count 
zcheck 25 lines printed 


:close print device 


N is the printer row # - 640 byte intervals [0,24] 


MM[O 
w[0} 


mov 
mov 


mov 
mov 
inc 
loop 


] = 40H,...,MM[3] 


01H (pel mask) 


= 128,w[1] = 64,...,w[7] =1 


si,0O 
cx, 320 


al,0 
coli{si],al 
si 

po110 


Figure 3.3 


scolumn count initialization 


3320 columns 


;clear print buffer 


sincrement column count 


(Continued) 
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mov 
mov 
mov 
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si,o 
N4,si 
dx, 80 


dai,o 
ddd, di 
cx, 8 


push cx 


mov 
add 


bp, ddd 
bp,N 


push es 
push mseli1 


Pop 
mov 
pop 


mov 
mov 
mov 
mov 


and 
mov 
shr 
mov 
mul 
mov 


mov 
and 
mov 
shr 
mov 
mul 
mov 


MOv 
and 
Mov 
shr 
mov 
mul 
mov 


mov 
and 
MOv 
shr 
mov 
mul 
mov 


es 
al,es: [bptsi] 
es 


s{0O],al 
s({1],al 
s[(2],al 
s(3],al 


al,MM[0] 

cl, shift1[0] 
al,cl 

ah,0 

w[di] 
b1[0],al 


al,s[(1] 
al,MM[1] 
cl,shift1[1] 
al,cl 

ah,0 

w{di] 
b1{1],al 


al,s(2] 
al,MM[2] 
cl,shift1[2] 
al,cl 

ah,0 

w[di] 
b1[2],al 


al,s[3] 
al,MM[3] 

cl, shift1[3] 
al,cl 

ah,0O 

w[di] 
b1[(3),al 


push bx 


mov 
mov 
add 
mov 
add 
mov 
add 
mov 
add 


bx, N4 
al,b1[0] 
coll[bx],al 
al,b1[1] 
coli[bx+1],al 
al,b1[2] 
coli[{bx+2],al 
al,b1[3] 
coll[bx+3],al 


; 

;index into 80 bytes/row 
7N4 = row byte block count 
;counter - row bytes 


t 

;raster row counter (1 of 8) 
780 block counter 

s;raster row counter 


;preserve row count 
sbp = # 80 byte blocks 
zadd printer line count 


sload address screen buffer 
74 pel bytes 


;1lst copy 

72nd copy 

73rd copy 

74th copy 

c 

;1lst pel mask 

zload 1st pel shift 
;shift right 

;Clear upper 

;multiply by weight (row) 
;save ist printer column 
a 

;load 2nd pel 

smask 2nd pel 

zload 2nd pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;save 2nd printer column 
sload 3rd pel 

;mask 3rd pel 

jload 3rd pel shift 
;shift right 

;Cclear upper 

;multiply by weight (row) 
;save 3rd printer column 
sload 4th pel 

;mask 4th pel 

zload 4th pel shift 
shift right 

;clear upper 

smultiply by weight (row) 
;save 4th printer column 


e 
v 


;preserve bx 

;counter into print buffer 
sload column N4 

tload column N4+1 

sload column N4+2 


sload column N4+3 


Figure 3.3. (Continued) 
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e 

;recall print block row index 
;increase print block row counter 
;increase byte count 

;decrease row bound 


sadd 4 columns to index 
;decrement row bytes 
s;increase screen buffer index 


DII2: 


ldarray 


s 
CSEG 


Figure 3.3. (Concluded) 


push bx 

lea bx,scr_buffer[0] 
add bp,bx 

mov al,ds:[bp+si}] 
pop bx 


This now reads 


push es 

push msell 

pop es 

mov al,es:[bp+si] 
pop es 


where the same buffer now appears starting at es:0000. 

Figures 3.1 through 3.3 represent simple examples of how to create and use a 
memory segment under OS/2. In this case the temporary screen buffer is created, 
accessed, and destroyed. Clearly, this technique can be used to manage memory 
within a given task. In the next section we consider the creation, access, and de- 
struction of a segment shared between two tasks. 
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3.2.2 Creating and Accessing a Shared Segment 


The program discussed in this section involves both a memory management function 
and multitasking. Although we do not formally address multitasking until Section 
3.3, it is useful to include it in this discussion because at least two processes are 
needed to demonstrate segment sharing. 

The program illustrated in Figure 3.4 opens with the following API call (which 
creates the shared segment): 


@DosAllocShrSeg shared_length,shrname,shrsel 


Here shared_length has been set at 404 bytes. These will correspond to 400 bytes (4 
extra bytes used to contain parameter data) that contain the corner values for boxes 
(xb, xe, yb, and ye). Further, these corner values will consist of numbers between 0 
and 200; hence the full height of the display screen will be used but only the first 
200 columns. 

The parameter shrname is a symbolic name to be associated with the shared 
memory segment to be allocated. The name string must include the prefix 


\SHAREMEM\... 
We choose 
‘\ SHAREMEM\SDAT.DAT’ ,o 


which is a zero-terminated string. Finally, shrsel is the shared segment selector. The 
name string for the shared segment must be common to all modules that use this 
segment and hence provides the link for ensuring that the same protected segment 
is accessed. 

In Figure 3.4, once the shared segment is allocated, the buffer contained in this 
segment is set to zero. Next a child process is executed using the statement 


@DosExecPgm obj_name_buf, lobj_name_buf, async, argptr, envptr, 
pid, prgm_nm 


where obj_name_buf is a buffer containing error pointers, lobj_name_buf is the 
length of this buffer, async = 1 indicates the two processes execute asynchronously, 
argptr = 0, envptr = 0, pid contains return codes, and prgm_num is the name of the 
file to be executed (in this case NOS261.EXE, which is zero terminated). This 
causes the process in Figure 3.5 to execute, NOS261.ASM. 

The process NOS261.ASM gets the shared segment using 


@DosGetShrSeg shrname, shrsel 


where the shared name, shrname, is the same but a new selector is assigned. Next, 
a sequence of random numbers are loaded into the shared segment locations based 
on the following formula [3]: 


X,4, = (2053 x, + 13,849) mod 2% (3.1) 
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PAGE 55,132 
TITLE 082512 - This is the calling OS/2 program (NOS2512.ASM) 


DESCRIPTION: This program plots boxes in protected 

mode and hesitates using a keyboard delay. Graphics 

mode 05H is used to display the boxes. It is the same 

as 0S24 except it uses external modules. This routine 
employs multitasking to access the input box parameters, 
which are generated randomly (100 boxes in square 200 x 200). 
The program prints graphics under program control. 


boxx: FAR, C1ls: FAR, C1SCGA: FAR, scr_1d:FAR,prtscr: FAR 


we fr] ~e © se we we Se we Me Me Me Ne 


viohdl,tr,lc,br,rc,no_line, blank, CGAm, lmodeE, typeCGA, colCGA 
txtcCGA, txtrCGA, hrCGA, vrCGA, STDm, lmode8s0, type80,col180 
txtc80,txtr8s0,hr8s0,vr80,waitf,dstat, PVBPtr1,bufstl1,buflenl,physell 
MASK1,MASK11,OFFSET1, four, xx, dummy, two, xxx, eighty, row,col 
address,x,y,xb,xe,ye,yb 


ee ee ee Gam aS SE GD SET ND GED GE ES GD GEE SI GE ED GD SUD GED GD GD GEE GED GEES GED GET GU GED GUD GUT GED GHP GED GUD GED GED GEN CUD GED GED OD CED GD On OF ED em OD ee ee oe ee oe oe oe oe oe oe 


Printscreen variables 


in_buffer,in_bufferi,in_buffer2,in_buffer3,in_buffer4 
bytesin, bytesin1,bytesin2,bytesin3,bytesout 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 

s,eight,eighty, four,shiftl1,scr_buffer 
sixforty,N4,ddd,w,b1 


include sysmac. inc 
ENDIF 
; 

-sall ;Suppresses macro lists 
agroup GROUP data 


STACK SEGMENT PARA STACK 'STACK! 
ab 256 dup('STACK  ‘') 
STACK ENDS 


DATA SEGMENT PARA PUBLIC ‘DATA’ 


viohdl equ ;Required video handle 
result dw ;Completion code 

action equ ;Terminates current thread 
tr dw ;Top row screen clear 

le dw ;Left column screen clear 
br dw ;Bottom row screen clear 
re dw ;Right column screen clear 
no_line dw ;Number lines scrolled 
blank dw ;Blank character pair 


f 


CGAm label ;Video mode structure-CGA 
lmodeE dw ;Structure length 

typecCGA db 00000111B ;Mode identifier 

colCGA db 2 ;Color option-Mode 5 

txtcCGA dw 40 ;text characters/line-ignore 
txtrCGA dw 25 ;text lines-ignore 


Figure 3.4 The program nos2512.asm, which creates a shared segment, creates 
a child process, and prints the screen. 
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hrCGA aw 320 
VrCGA aw 200 
v 

SsTDm label FAR 
lmodesg0 dw 12 
types0 db Q90000001B 
col8s0 ab 

txtc80 dw 

txtr8s0 dw 

hrs0 aw 

vr8s0 dw 


kbd_buf db 

lkbd_buf dw 

iowait dw 

kbdhdl equ 

waitf equ 

dstat db 

PVBPtri1 label FAR 
bufst1 dd OB8000H 
bufleni1 dd 8000H 
physell dw 0 


MASK1 ab 01H 

MASK11 dw 0001H 
OFFSET1 dw 2000H 
four dw 
XX dw 
dummy dw 
two ab 
XXX ab 
eighty dw 
zero dw 
one dw 
row dw 
col dw 
address dw 


YVVVE OO VN Vv & 


dw 

dw 
xb dw 
xe dw 
yb dw 
ye dw 
‘ 
obj_name_buf 
lobj_name_buf 
async dw 
argptr dw 
envptr dw 
pid dw 

dw 
prgm_nm db 


VV eV OV oN oo) 


Q 
Q 


10 dup(0) 
$-obj_name_buf 


eVIVO OF 


NOS261.EXE',0 


shared_length dw 404 
shrname db '\SHAREMEM\SDAT. DAT! , 0 
shrsel dw z 

; 
ESDI 
count 


400 dup(?) 
rg 


me to tO NO 
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shorizontal resolution 
;vertical resolution 


;Video mode structure-80x25 
?Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

stext lines 

shorizontal resolution 
svertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

70S/2 screen buffer selector 


;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


;row 
;column 
;Address screen dot 


;Box col parameter 
;Box row parameter 
;Start column 

7End column 

:Start row 

7End row 


;object name buffer 
;buffer length 

;Flag indicates async 
70 for argument ptr 

70 for environment ptr 
;Process ID result code 


sprogram name & parameter 
;Length shared buffer 
selector 


;Buffer for shared data 
:Buffer size in bytes 
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eight dw 
in_buffer 
in_buffer1 
in_buffer2 
in_buffer3 
in_buffer4 
bytesin 
bytesinl 
bytesin2 
bytesin3 
bytesout 


’ 


dev_name 


320 dup(0) 


1Bh, 4BH, 64D, 01H 


ODH, OAH 


1BH, 41H, 08H 


sprint buffer 
;printer setup 
;LF/CR 


e 
s 


sprint buffer count 

zcount bytes in_buffer1l 
zcount bytes in_buffer2 
;count bytes in_buffer3 


zname of printer device 


dev_hand 
dev_act 
dev_size 
dev_attr 
dev_flag 
dev_mode 
dev_rsv dd 


N4 dw 
MM db 
w db 
coll db 
bl db 
N dw 
shift1l db 
s ab 
ddd dw 
sixforty 

scr_buffer 


00000001b 


0000000011000001b 


40H, 10H, 04H, 01H 
128,64,32,16,8,4,2,1 
320 dup(?) 

4 dup(?) 

° 


6,4,2,0 
4 dup(?) 
? 


dw 640 
16384 dup(0) 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 


sdevice handle 


’ 


e 
e 


sopen file 


spel mask 
spin weights 
;columns 


;temporary buffer 


;hdl private,deny none,w/o 


PROC FAR 


@DosAllocShrSeg shared_length, shrname, shrsel 


cmp ax,0 
jz NO_ERROR1 
jmp ERROR1 


NO_ERROR1: 


° 
, 


push shrsel 
pop es 


mov ax,one 


mov es:{2],ax 


mov ax,shared_length 


mov es:[0]},ax 


mov di, four 


mov cx,shared_length 


sub cx, four 
mov ax,zero 


mov es:(dij,al 


inc di 
loop lloop 


;Check on successful creation 
Successful 
s;Error 


° 
a 


;Save selector 
:Selector in extra segment 


° 
’ 


?Flag indicating creation 


; 
;Length shared buffer 
Length parameter passed~-multitask 


e 
’ 


;Data record offset in buffer 
:Data buffer length + 4 

:Data buffer length 

Clear character 


:Clear buffer 
7Next buffer point 


Figure 3.4 (Continued) 
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@DosExecPgm obj _name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 


cmp ax,0 
jz NO_ERROR2 
jmp ERROR2 


mov ax,zero 


cmp es:(2],ax 
jz MEM_CL 
jmp NO_ERROR22 


mov si,zero 
mov di,four 
mov cx,shared_length 
sub cx, four 
mov count,cx 


mov al,es: [dij 
mov ESDI[{si],al 
inc di 

inc si 

loop loop22 


call cls 

@vioSetMode CGAm,viohdl 

call clsCGA 

@vioScrLock waitf,dstat,viohdl 
@vVioGetPhysBuf PVBPtr1,viohdl 
push physell 

pop es 


mov di,0O 

mov dax,0 
mov ax,count 
div four 
mov cx,ax 


push cx 

mov al,ESDI[di] 

mov ah, ESDI[di+1]} 

cmp ah,al 

jne EELSE1 
mov al,170 
mov ah,180 
call xload 
jmp IIF1 


cmp ah,al 

jle ELSE1 
call xload 
jmp IIF1 


mov bl,al 
mov al,ah 
mov ah,bl 
call xload 


mov al,ESDI[di+2] 
mov ah,ESDI(di+3]} 
cmp ah,al 
jne EELSE2 


Memory Management Activities 


;Check error condition 
;Jump no error 
;dJump error 


;Indicates buffer write complete 


:Check buffer write 
;Jump if buffer write complete 
;Otherwise wait 


;Offset in intermediate buffer 
;Offset in shared buffer 
;Length data buffer + 4 
;Length data buffer 

;Data buffer size in bytes 


;Obtain shared buffer value 
;Load shared memory buffer 
;Increment shared buffer ptr 


;Increment intermediate buffer ptr 


sClear screen 

;Set CGA graphics mode 

7;Clear CGA screen 

;Lock screen context 

7Get physical buffer selector 
;Save selector 


;Load selector into extra segment 


;Intermediate buffer offset 
;Clear upper dividand 

;Data buffer byte count 
;Reduce to sets of four 
;Loop count 


;Save loop count 

;Obtain lst buffer value-set 
;Obtain 2nd buffer value-set 
;Check values equal 


;Arbitrarily set 1st equal value 
;Arbitrarily set 2nd equal value 


;Load xb and xe 


7Check ah g.t. al 


s;Load xb and xe 


;Swap ah and al 


s;Load xb and xe 


;Obtain 3rd buffer value-set 
;Obtain 4th buffer value-set 
;Check values equal 
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mov al,170 
mov ah,180 
call yload 
jmp IIF2 


cmp ah,al 

jle ELSE2 
call yload 
jmp IIF2 


mov bl,al 
mov al,ah 
mov ah,bl 
call yload 


push di 
call boxx 
pop di 

add di, four 


pop cx 
loop loop2 


call scr_ld 


@VioScrUnLock viohdl 


;Arbitrarily set 1st equal value 
;Arbitrarily set 2nd equal value 
;Load yb and ye 

:Check ah g.t. al 


;Load yb and ye 


;Swap ah and al 


;Load yb and ye 

Save buffer offset 

Draw box 

:Recall buffer offset 
sIncrement data ptr 4 bytes 


7Recall loop count 


zload screen print buffers 


sUnlock screen context 


@KbdStringIn kbd_buf,1lkbd_buf, iowait,kbdhdl rhesitate 


@VioSetMode STDn,viohdl 


@DosKillProcess 1,pid 
@DosFreeSeg shrsel 


call prtscr 
@DosClose dev_hand 
@DosExit action,result 


ENDP 


PROC NEAR 
mov bh,0 

mov bl,al 
mov xb,bx 
mov bh,0 

mov bl,ah 
mov xe,bx 
ret 

ENDP 


PROC NEAR 
mov bh,0O 

mov bl,al 
mov yb,bx 
mov bh,0 

mov bl,ah 
mov ye,bx 
ret 

ENDP 


ENDS 
END 0S21 


Figure 3.4 


780 x 25 alpha mode 
?Terminate child process 


;Free shared memory 


7Terminate process 


;Clear upper register half 
sal = start 

s;Load xb less than 199 
;Clear upper register half 
sah = end 

s;Load xe less than 199 


;Clear upper register half 
ral = start 

;Load yb less than 199 
;Clear upper register half 
;ah = end 

;Load ye less than 199 


(Concluded) 
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TITLE OS261 - Generates multitask r.n. (0S261.ASM) 


fd we © we we te Of 


ENDIF 


dgroup 


’ 
STACK1 


STACK1 


‘ 
DATA1 


rnd 
; 


one 
action 
result 
ssize 
shrsel 
shrname 
zero 


eo 


’ 
DATA1 


‘ 
CSEG1 


08261 


7 


Figure 3.5 The child process nos261.asm, used to generate random numbers in 
a Protected Mode multitasked environment. 


DESCRIPTION: This process generates the multitasked 


random numbers. 


include sysmac.inc 


-sall 
GROUP datal 

SEGMENT PARA STACK ‘STACK! 
db 256 dup('STACK1 ‘') 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 
daw 


aw 
equ 
aw 
aw 
aw 


ab \SHAREMEM\SDAT.DAT' , 0 


aw 0 
ENDS 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:csegl1,ds:dgroup 
PROC FAR 


mov ax,one 
mov rndl1,ax 

@DosGetShrSeg shrname,shrsel 
push shrsel 

pop es 


mov ax,es:[(0] 
mov ssize,ax 


mov di,4 
mov cx,ssize 
sub cx,4 


mov al,0O 

mov es:[(di],al 
inc di 

loop loopl 


mov di,4 
mov cx,ssize 


sub cx,4 


call ldmem 
mov es:{di],al 
inc di 

loop loop2 


It is called by the plot process. 


;Suppresses macro lists 


;seed value 


;Buffer size + 4 
:;Selector 
;Shared memory name 


sLoad initial seed value 


;Get shared segment 
;Save selector 
;Selector to extra segment 


sEstablish shared buffer size 
:;Define buffer size + 4 


;Pointer to data buffer 
;Loop byte count + 4 
;Loop byte count 


;Clear buffer 
7;Buffer write 
sIncrement offset 


:Pointer to data buffer 
;Loop byte count + 4 


;Loop byte count 


?Generate random value 
;Load shared buffer (byte) 
:Increment byte offset 
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mov ax, zero 
mov es:[2],ax 


@DosFreeSeg shrsel 
@DosExit action,result 
ENDP 

PROC NEAR 

mov ax,0 


mov ax,rndl 
mov bx,2053 


; 
?Flag indicating write complete 
?Flag loaded 


;Generate r.n. 

;Load upper multiplicand zero 
;Load previous r.n. 
;Multiplier 


mul bx 
mov bx,13849 
cle 


sLoad additative constant 


add ax,bx ;Add@ low order result 
adc dx,0 ;Add carry if needed 
mov bx, OFFFFH sLoad 2(16) - 1 

div bx ;Calculate modulo 

mov ax,ax ;Move remainder into ax 
mov rndil,ax ;Save r.n. 

mov bx,350 ;Scale r.n. to less than 200 
mov ;Clear upper dividand 
div ;Scale 

MOv ;Save al 

ret 

ENDP 


ENDS 
END 0S261 


Figure 3.5 (Concluded) 


Here x,,, is the (n + 1)th number and x, the mth number(s). The procedure ldmem 
contains the code that calculates this random sequence. Once the sequence is calcu- 
lated, the size of the buffer is checked. This size was loaded as a word at es:[0] in 
the creating routine. In NOS261.ASM the value is used to set the number of random 
values to be calculated (here this is 400). 

Next, NOS261.ASM frees the shared segment using 


@DosFreeSeg shrsel 


and exits back to OS/2. Prior to freeing the segment, however, NOS261.ASM loads 
a zero at es:[2] to indicate that the buffer write is complete. (This value was previ- 
ously set to 1.) The main calling program, NOS2512.ASM, sits in a loop checking 
es:[2] for a value of zero. (This is a somewhat wasteful operation and could be used 
asynchronously to accomplish other tasks if needed.) Once the random values have 
been completely loaded and NOS2512.ASM becomes aware of this, it terminates the 
loop and reloads these shared values into a buffer, ESDI. The processing then 
continues in the usual fashion to clear the screen, set the CGA mode, and capture 
the physical screen buffer. Using two routines, xload and yload, the box corners are 
loaded, ensuring that (xb, yb) are always less than (xe, ye), respectively. The rou- 
tine boxx is called and the random boxes generated on the display. Figure 3.6 illus- 
trates the variant of boxx used for this call. Note that it includes a check on the 
corners to ensure that xb < xe and yb < ye. 
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TITLE OS252 - Supplemental routines for box plotting (0S252.ASM) 


me te Se we te MNO 


EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
, 
CSEG 
PUBLIC 


boxx 


=e Te Se 


ELSE10: 


ELSE11: 


Figure 3.6 Supplemental routines needed by the random box generating 


DESCRIPTION: These routines set up box plots in CGA 
mode and hesitate using a keyboard delay. Graphics 
mode 05H is used to display the box. This set of routines 


PAGE 55,132 


is called by box plotting main routine. 


include sysmac.inc 


-sall 


;Suppresses macro lists 


viohdl: WORD, tr:WORD, 1c:WORD, br:WORD, rc: WORD 


no_line:WORD, blank: WORD, CGAm: FAR, lmodeE: WORD, typeCGA: BYTE 
CO1CGA: BYTE, txtcCGA: WORD, txtrCGA:WORD, hrCGA: WORD, vrCGA: WORD 
STDm: FAR, lmode80:WORD, type80: BYTE, col80: BYTE, txtc80:WORD, txtr80:WORD 


hr80:WORD,vr8s 


0:WORD 


waitf:WORD,dstat: BYTE, PVBPtr1: FAR, bufst1: DWORD 


buflen1: DWORD, physel1:WORD, MASK1: BYTE, MASK11: WORD, OFFSET1: WORD 
four: WORD, xx: WORD, dummy: WORD, two: BYTE, xxx: BYTE, eighty: WORD 
row:WORD, col: WORD, address: WORD, x: WORD, y: WORD, xb: WORD, xe: WORD 


yb:WORD, ye: WORD 


SEGMENT PARA 


PUBLIC ‘CODE! 


cls,boxx,c1lsCGA 
assume cs:cseg 


PROC FAR 


xb = x-begin,xe = x-end,yb = y-begin,ye = y-end 


mov ax,xb 

cmp ax, xe 

j1 ELSE10 
xchg ax, xe 
mov xb,ax 


mov ax,yb 

cmp ax,ye 

jl ELSE11 
xchg ax,ye 
mov yb,ax 


mov ax,yb 
mov y,ax 
call lineh 
mov ax,ye 
mov y,ax 
call lineh 
mov ax,xb 
mov X,ax 
call linev 
mov ax, xe 
mov x,ax 
call linev 


ret 
ENDP 


PROC FAR 


;Check xb 1.t. 


;Swap xb and xe 


;Check yb 1.t. 


:Swap yb and ye 


*Top box line 


;Draw top horizontal line 


xe 


ye 


7;Bottom box line 


;Draw bottom horizontal line 


:Left box line 


Draw left vertical line 
*Right box line 


;Draw right vertical line 


@vioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


routine, nos2512.asm. 
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cls 


‘ 
clsCGA 


e 
a 


ret 


ENDP 


PROC FAR 


@VioScrLock waitf,dstat,viohdl 


@VioGetPhysBuf PVBPtri,viohdl 
push physeli 
pop 


mov 
mov 


mov es: [bp],al 
inc bp 

cmp bp,1F3FH 
jle DO1 


mov bp, 2000H 
mov al,0O 


mov es: [bp],al 
inc b 

cmp bp,3F3FH 
jle DO2 


@VioScrUnLock viohdl 


ret 
ENDP 


PROC NEAR 


(col,row) = (x,y) 


fild four 
fild col 
fprem 

fistp xx 
fistp dummy 
mov al,3 

mov bl,byte ptr xx 
sub al,bl 
mov ah,O 

mul two 

mov cl,al 
mov al,MASK1 
shl al,cl 
mov xXxx,al 


mov ax,row 

shr ax,1 

mov dax,0 

mul eighty 

mov bx,col 

shr bx,1 

shr bx,1 

add ax,bx 

mov address,ax 

Mov ax, row 

and ax,MASK11 

cmp ax,0 

jle ELSE1 
mov ax,address 
add ax,OFFSET1 
jmp IF11 


Memory Management and Multitasking with Assembler 


;Lock screen context 
;Get physical buffer 
;Screen selector 
;Load extra segment 


sStart offset zero 
:Zero attribute-clear 


;Clear byte 


;Check end ist buffer 


;O0ffset 2nd buffer-odd 
;Zero attribute-clear 


*Clear byte 


;Check end 2nd buffer 


Unlock screen context 


sLoad stack with 4 

*ST = col, ST(1) = 4 
sModulo 

;Store remainder in xx 
7;Pop stack 


7(3 - col % 4) 
;Clear upper multiplicand 


;Shift value for PEL 
;PEL color mask 
;Shift to correct PEL 
;Store buffer value 


° 
a 


;Begin address calculation 
;Divide row by 2 
;Clear upper multiplicand 


;Convert column value to bytes 


;offset in ax 

sSave offset base 
;Check even/odd row 
;Look for bit 0 set 


sadd odd buffer offset 


Figure 3.6 (Continued) 
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mov ax,address 


mov bp, ax ;screen buffer address 
mov al,xxx ;Attribute value for dot 


or es:[{bp),al ;Write dot 


ret 
ENDP 


PROC NEAR 
y = row position, xb = begin, xe = end 


MOV ax,y ;Establish row for wdot 
mov row,ax 


mov ax,xb sEstablish start column 


mov col,ax 

push ax :Save column value 

call wdot :Write dot (col,row) 

pop ax ;Recall column 

inc ax ;Increment column 

cmp ax, xe ;Check end horizontal line 
jle DO10 

ret 

ENDP 


PROC NEAR 
x = col position, yb = begin, ye = end 


mov ax,X ;Establish column for wdot 
mov col,ax 


mov ax,yb ;Establish start row 


mov row,ax 
push ax ;Save row value 
call wdot ;Write dot (col,row) 
pop ax ;Recall row 
inc ax ;Increment row 
cmp ax,ye ;Check end vertical line 
jle DO20 
; 
ret 
ENDP 


ENDS 
END 


Figure 3.6 (Concluded) 


Once the boxes are plotted the keyboard hesitate takes place, followed by a 
call to prtscr that prints the screen content. A similar version of this program appears 
in reference 4, without the screen print logic. Figure 3.7 illustrates the plotted boxes. 


3.2.3 Changing Segment Size 


Among the API memory management services are functions for changing the size of 
an allocated segment. It is a prerequisite, however, that the segment be allocated 
during the existing session. Figure 3.8 presents a program that allocates and then 
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Figure 3.7 Screen print of the 100 
random boxes output by nos2512.asm. 


modifies the size of a segment. This program is somewhat artificial in that it serves 
no useful purpose other than to demonstrate this memory management technique. 
The program opens with the call 


@DosAllocSeg msize, msell, mflag 


Here msize is the desired size of the segment (in this case 4000H), in msell the 
returned selector, and mflag determines the type of segment access. Specifically, bits 
O and 1, when set, permit sharing of the segment using DosGiveSeg and DosGetSeg, 
respectively. Bit 3 allows the segment to be discarded in low-memory situations. If 
the segments are shared, they can only be increased in size. We have set all three 
of these bits to 0. 

The next block of code pushes the allocated segment selector on the stack and 
pops it into es. Hence, es now points to the created segment. This segment is loaded 
with 2048 copies of the string “MEMORY ”, where two blank spaces have been 
added to the end of the string. Once completed, the call 


@DosReallocSeg msizel, msell 


is made and the segment size reduced to one byte beyond a paragraph boundary. At 
this point some mechanism must exist to check the segment definition. Subsequent 
code writes a 1 into the first location of the segment, followed by a write to the 
eighteenth position. The latter position should yield a protection violation. 

Figure 3.9 illustrates CodeView results for the program following creation of 
the memory segment. Note that beginning at address es:0x0000 (here 0x0000 speci- 
fies a hexadecimal address, 0000, in C notation), the string “MEMORY ” is loaded. 
A check at 0x4000 shows that the preceding 4000H locations are filled with this 
string also (Figure 3.9b). 
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TITLE MEMSEG -- Reallocate memory segment (memseg.asm) 


bq we we te te Ye & 


Fl 


ENDIF 


; 
dgroup 
STACK 
STACK 


DATA 

a 
msize 
msell 
mflag 
blk_ct 
mem_wd 
msizel 


DATA 


CSEG 


0S21 


Figure 3.8 


DESCRIPTION: This simple routine creates and reallocates 


a memory segment. 


should be run with CodeView. 


include sysmac.inc 


-sall 
GROUP data 

PARA STACK ‘STACK’ 
256 dup ('STACK 


SEGMENT 
ab 
ENDS 


‘) 


SEGMENT PARA PUBLIC 'DATA'* 
aw 16385 

dw ? 

dw 0000000000000000B 
aw 16384 

ab 'M',"E', 'M','oO!','R!, 
dw 17 


ENDS 
SEGMENT PARA PUBLIC 'CODE! 
assume cs:cseg,ds:dgroup 

PROC FAR 
@DosAllocSeg 


push msell 
pop es 


mov 
mov 
lea 


ax,blk_ct 
di,o 
bp,mem_wd 


mov 
mov 


cx, 8 
si,0 


mov 
Mov 
inc si 
inc di 
loop LOOP2 


al,ds: (bp+si] 
es:(dij],al 


cmp di,dx 
jl Loopi 


@DosReallocSeg msizel,msell 


push msell 

pop es 

mov bp,0 

mov al,l 

mov es:{bp],al 
mov es: [(bp+17],al 


tyr j 


msize,msell,mflag 


The final memory instruction is 
designed to create a protection violation. 


The program 


sbuffer size 
s;selector 

snot sharable 
sblock count 

' t,' ' sstring 
tnew buffer size 


sallocate segment 


sblock counter limit 
sbuffer block count 
sstring address 


scount limit for string 
:index for string/buffer 


zload from string 
sload buffer 
sincrement string 
;increment block byte 


scheck block limit 


sreallocate segment 


*preserve selector 
;create extra segment 
;segment index 

;load dummy value 
:single load in buffer 
7;PROTECTION VIOLATION 


Simple routine for creating and reallocating memory. 
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@DosExit 1,0 


0S21 ENDP 
CSEG ENDS 
END 


Figure 3.8 (Concluded) 


Calls Trace! Go! MEMSEG . EXE 


003F:002F 268805 MOV Byte Ptr ES: [{DI],AL 
003F:0032 46 INC I 

003F:0033 47 

003F:0034 E2F6 

003F:0036 3BFA 

003F:0038 TCEC 

Q03F:003A A11000 


IBM CodeView (R) Version 1.00 

Copyright (C) IBM Corporation 1987 

Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

OO6F:0000 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0010 4D 45 4D 4F 52 59 20-4D 45 4D 4F 
OO6F:0020 4D 45 4D 4F 52 59 20-4D 45 4D 4F 
OO6F:0030 4D 45 4D 4F 52 59 20-4D 45 4D 4F 
OO6F:0040 4D 45 4D 4F 52 59 20-4D 45 4D 4F 
OO6F:0050 4D 45 4D 4F 52 59 20-4D 45 4D 4F 
OO6F:0060 4D 45 4D 4F 52 59 20-4D 45 4D 4F 
OO6F:0070 4D 45 4D 4F 52 59 20-4D 45 4D 4F 

> 


(a) 


Figure 3.9 Facsimile CodeView output, illustrating (a) low end of initialized memory 
segment and (b) high end of initialized memory segment. (Courtesy of the Microsoft 
Corporation.) 
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= File Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 


seoeeen sersrsnesesetasnnnet Sy aaa 


OO0O3F:002C 3E8A02 MOV AL,Byte Ptr DS: [BP+SI] 
OO3F:002F 268805 Byte Ptr ES: [DI],AL 
OO3F:0032 46 SI 

003F:0033 47 DI 

003F:0034 E2F6 002C 

003F:0036 3BFA DI, DX 

003F:0038 7CEC 0026 

003F:003A A11000 AX,Word Ptr [0010] 


OO6F:0060 4D 20-4D 45 4D 4F 52 59 MEMORY MEMORY 
OO6F:0070 4D 45 20-4D 45 4D 4F 52 59 MEMORY MEMORY 
>d es: 0x3ff0 

OO6F:3FFO 4D 45 20-4D 45 4D 4F 52 59 MEMORY MEMORY 
OO6F: 4000 ?? 22 29 99 29 292 29 29-29 22 229 22 22 2? 

OO6F:4010 79 292 29 22 29 92 22 29-229 22 22 229 22 2? 

OO6F: 4020 ?2 22 29 292 29 29 22 29-22 22 2929 22 22 29 

OO6F:4030 ?7 29? 29 22 22 22 92 29-29 292 22 22 229 2? 

OOBF: 4040 79 22 22 22 29 29 292 29-229 229 22 22 22 29 

OO6F: 4050 7? 22 27 22 229 29 229 29-229 22 22 22 22 29 

OO6F: 4060 77 292 22 22 29 92 292 29-229 22 22 22 22 29 

> 


(b) 
Figure 3.9 (Concluded) 


Figure 3.10a corresponds to execution up to 003F:0055, in which the resized 
segment now has its first location loaded with 1. Figure 3.10b corresponds to exe- 
cution of 003F:0055 and the subsequent violation is noted. 

Figure 3.11 illustrates CodeView output for the case when a segment violation 
might occur except that the segment is defined as sharable with bits 0 and 1 of 
mflag set. In this case the attempt to reallocate the size of the segment downward 
to 17 bytes fails and the initial segment size remains implemented. The instruction 
003F:0055 executes as the segment data indicate. 


3.2.4 Creating and Accessing Huge Segments 


The OS/2 kernel (level 0) allocates and maintains segment descriptors. This provides 
a mapping of the virtual address space onto the physical memory space. OS/2 does, 
in fact, allow the user the capability to request and use more memory than exists in 
his or her system. This is accomplished using extended file management techniques. 
A very key boundary under DOS and within the confines of the Intel 8086 family 
of architectures is the 64K boundary or segment size. OS/2 has API services that 
allow the user to extend a huge memory block because the underlying segments are 
still in place. The system simply provides additional selectors, as needed, to access 
the subsequent high-memory spaces. 
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= File Search View Run Watch Options Calls Trace! Go! MEMSEG . EXE 


ee 


O03F:0042 9A0000B345 CALL 45B3:0000 
003F:0047 FF360200 PUSH Word Ptr [0002] 
O03F:004B 07 POP 

003F:004C BDOOOO MOV 

O03F:004F BOO1 MOV 


003F:0051 26884600 MOV Byte Ptr ES: (BP+00], AL i 
OO3F:0055 26884611 MOV Byte Ptr ES: [BP+ii], AL S 
003F:0059 B80100 MOV AX,0001 


LS i 


Copyright (C) IBM Corporation 1987 

Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

OO6F:0000 01 45 4D 4F 52 20 20-4D 45 4D 4F 52 .EMORY MEMORY 
OO6F:0010 77 299 72 22 22 22 29 229-22 22 22 92 29 
OO6F:0020 72 22 292 22 22 22 22 229-22 22 292 22 22 
OO6F:0030 79 22 2? 292 22 22 22 229-22 292 292 22 «92 
OO6GF:0040 ??2 2? 22 292 22 22 22 29-22 22: 972 22 «29 
OO6F:0050 2? 2? 22 2? 22 22 22 29-22 22 292 2? 2? 
OO6F:0060 7? 2? 22 22 22 29 22 299-22 22 92 22 22 
OO6F:0070 77 29 29 292 299 29 29 29-22 22 22 92 29 
» 


= File Search View Run Watch Options Calls Trace! I MEMSEG . EXE 


er a a a peice ae ge ne ee ee ee 


0O03F:0042 9AD000B345 CALL 45B3: 0000 

003F:0047 FF360200 PUSH Word Ptr [0002] 
003F:004B POP ES 

003F:004C BP ,0000 

003F:004F AL,O1 

003F:0051 26884600 Byte Ptr ES: [BP+00],AL 
OO3F:0055 26884611 Byte Ptr ES: [BP+11],AL 
003F:0059 B80100 


Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

OO6F:0000 O01 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6GF:0010 ?? 2? 29 22 292 229 9? 99-229 22 292 292 2° 
OOBF:0020 729 22 27 22 22 29 22 2929-22 22 22 22 29 
OOBF:0030 79 22 22 29 297? 92 229 299-227 22 229 22 «29 
OO6F:0040 729 22 22 22 22 22 22 2929-229 22 22 22 2% 
OO6F:0050 7? 2? 22 22 22 22 22 22-2929 29 92 22 2° 
OO6GF:0060 72? 2? 22 292 22 22 22 229-227 229 22 22 2 
OO6F:0070 72 27 22 22 22 22 22 29-2929 292 22 22 22 
>Segmentation violation 


(b) 


Figure 3.10 Facilimile CodeView output, illustrating (a) reallocated memory and (b) 
reallocated memory with protection violation. (Courtesy of the Microsoft Corporation.) 
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= File Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 
eee ee 
003F:0042 9A0000B345 CALL 45B3:0000 
003F:0047 FF360200 PUSH Word Ptr [0002] 
003F:004B 07 POP 
003F:004C BDOOON MOV 
003F:004F BOOL1 MOV 
003F:0051 26884600 MOV Byte Ptr ES: [BP+00],AL 
003F:0055 26884611 MOV Byte Ptr ES: [BP+11],AL 

3F:0059 B80100 AX, 0001 


O7E7:0060 4D 45 20-4D 
O7E7:0070 4D 20-4D 
>d es:0x0000 

0O7E7:0000 20-4D 
07E7:0010 20-4D 
07E7:0020 20-4D 
07E7:0030 20-4D 
O07E7:0040 20-4D 
07E7:0050 20-4D 
07E7:0060 20-4D 
O7E7:0070 20-4D 
> 


Figure 3.11 Facsimile CodeView output, illustrating reallocated memory for the conditions 
of Figure 3.10b with sharable memory. Note: There is no protection violation. (Courtesy 
of the Microsoft Corporation.) 


Figure 3.12 illustrates a program hugeseg.asm, which is used for allocating 
such a huge segment. In this case 81,920 bytes are allocated. The initial call is 


@DosAllocHuge mnumseg, msize, msell, msegmax, mflag 
where 


mnumseg number of 64K whole blocks in segment 


msize number of bytes in last non-whole block 

msell selector 

msegmax maximum number of 64K whole segments occupied 
(set = 0 means the segment can only be decreased) 

mflag bit O=1 (shareable through DosGiveSeg) 


bit 1=1 (shareable through DosGetSeg) 
bit 2=1 (discardable in low-memory cases) 


In the program we use one 64K whole segment and a partial memory block of 


16,384 bytes. The initial selector value returned by @DosAllocHuge points to the 
first block in the huge segment. Subsequent blocks must be accessed using 
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TITLE HUGESEG ~- Allocate a huge segment (hugeseg.asm) 


using CodeView. 


a | =e %8 “eo Se NO 


Fi 
include sysmac.inc 
ENDIF 
-sall 
dgroup GROUP data 


STACK SEGMENT PARA STACK 'STACK' 
db 256 dup ('STACK  ‘') 
STACK ENDS 


a 
DATA SEGMENT PARA PUBLIC 'DATA'‘ 


e 
’ 


mnumseg dw 1 

msize dw 16384 

msell dw ? 

msegmax dw fe) 

mflag dw 0000000000000111B 
blk_ct dw 8192,2048 

shift_ct dw 2 

mem_wd db TM ey Mt O's TRI ty, 
mseg_ct dw 1 

two dw 2 


’ 
DATA ENDS 


CSEG SEGMENT PARA PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup 
0S21 PROC FAR 


DESCRIPTION: This program allocates a huge segment: 
2 (65536) and 1 (16384) byte 64k blocks. It is checked 


;suppresses listing 


snumber 64k whole blocks 
sbytes in last block (partial) 
;selector : 

;maximum realloc 64k blocks 
;segment characteristics 
sbytes in each block 


;shift count 


' ¢ ¢ 8 
? 


;block counter (0,1) 


@DosAllocHuge mnumseg,msize,msell,msegmax,mflag 


mov si,0 
push si 


pop si 

mov ax,mseli 
cmp si,1 

jl ELSE1 


@DosGetHugeShift shift_ct 
mov bx,1 

mov cl,byte ptr shift _ct 
shl bx,cl 

mov ax,msell 

add ax,bx 


mov msell,ax 


push si 

mov ax,si 

mul two 

mov si,ax 

mov dx,blk_ct[si] 
pop si 


sblock index 
;preserve index 


srecall block index 
sload selector 

scheck if 1st block 
;jump if 1st block 


¢ 

;get shift count 

sbx to be shifted 
zload shift as byte 
samount shifted 
7reload selector 
7create new selector 


sreload selector 


sblock byte sount 


Figure 3.12 The program hugescg.asm, used for allocating a huge segment 


(81,920 bytes). 


Chap. 3 


Memory Management Activities 


mov di,0O 

lea bp,mem_wd 
inc si 

push si 

push msell 
pop es 

mov cx,dax 


mov si,O 
mov al,ds: (bpt+si] 


mov es: [(dij,al 
inc 


sblock internal index 
s;address "MEMORY " 
;increment block count 
;preserve block count 
;selector 

:selector in es 

sload block string count 


;string index 


;load string member 
;insert in huge segment 


;increase string index 


123 


inc ;increase huge segment index 
cmp ;check string count 
jle 

loop LOOP1 

pop si ;recall block count 
cmp si,mseg_ct ;last block? 

push si ;preserve block count 
jle LOOP3 

@DosFreeSeg msell 

@DosExit 1,0 

ENDP 


ENDS 
END 


Figure 3.12 (Concluded) 


@DosGetHugeShift. This provides a shift count that can be used to calculate an off- 
set. Note that the call 


@DosGetHugeShift shift_ct 


returns a shift count in shift_ct. The selector offset increment is obtained by shift- 
ing the value 1 to the left by the amount specified as the shift count, shift_ct. This 
is then added to the selector value to get the new selector. For example, suppose 
that the selector is 6F7H. If the shift count returned is 4, an increment of 16 must 
be added to 6F7H to get the new selector: 707H. If several blocks have been allo- 
cated, the selector for each must be obtained by adding the increment to each suc- 
cessive selector to obtain the following value. 

In Figure 3.12 a check is made on whether the first block is being processed 
(si less than 1) and the shift count processing implemented as needed. The word 
“MEMORY ~” is then written into the memory block. Finally, the block is released 
using @DosFreeSeg. Figure 3.13 illustrates the CodeView memory dump starting at 
07F7:FFFO, the end of the segment. Since the listing wraps around at 07F7:FFFF, it 
is clear that the 64K block is filled with “MEMORY ”. Figure 3.14a illustrates the 
beginning of the last partial segment and Figure 3.14b the end of this partial seg- 
ment (16,384 bytes long). The partial segment is, of course, also loaded with 
“MEMORY ”, indicating that the allocation and use of the huge segment (81,920 
bytes) was successful. 
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= File Search View Run Watch Options Calls Trace! Go! HUGESEG. EXE 


003F:0068 BEOO00 MOV ST,0000 

003F:006B MOV AL,Byte Ptr DS: [BP+SI] 
003F: 006E MOV Byte Ptr ES: [DI], AL 
003F:0071 

003F:0072 

003F:0073 

003F:0076 

003F:0078 

O003F:007A 


O7F7:0070 4D 
>d es: Oxfff0 
O7F7: FFFO 
O7F7:0000 
07F7:0010 
07F7:0020 
O7F7:0030 
O7F7:0040 
07F7:0050 
O7F7: 0060 

> 


Figure 3.13 Facsimile CodeView output, illustrating loading through first 64K block limits 
(07F7:0000 through 07F7:FFFF) of huge segment. (Courtesy of the Microsoft Corporation.) 


= File Search View Run Watch Options Calls Trace! Go! HUGESEG. EXE 
SS Se 


OO3F:O006E 268805 MOV Byte Ptr ES:{DI]},AL 
OO3F:0071 46 INC SI 

0O3F:0072 47 INC 

003F:0073 83FE07 

003F:0076 TEF3 

O03F:0078 E2EE 


:00 
003F:007B 3B361800 SI,Word Ptr [0018] 


Copyright (C) IBM Corporation 1987 
Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

0807:0000 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0010 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0020 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0030 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0040 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0050 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0060 4D 45 4D 4F 52 59 20 20-4D 45 4D 
0807:0070 4D 45 4D 4F 52 59 20 20-4D 45 4D 
> 


Figure 3.14a Facsimile CodeView output, illustrating (a) loading of second block start 
(0807:0000) and (b) loading through second block end (0807:3FFF) of huge segment. 
(Courtesy of the Microsoft Corporation.) 
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Search View Run Watch Options Calls Trace! Go! HUGESEG. EXE 


iene | as 


O03F:007B 3B361800 CMP | SI,Word Ptr [0018) = 
O03F:007F 56 PUSH SI i 


003F: 0080 JLE 0022 
003F:0082 MOV AX,Word Ptr [0004] 
:0085 PUSH AX 
:0086 9AOOO0BB45 CALL 45BB: 0000 
:008B B80100 AX,0001 
:008E 50 
:008F B80000 


0807:0070 4D MEMORY MEMORY 
>d es:0x3ff0 

0807:3FFO 4D MEMORY MEMORY 
0807:4000 °?? 

0807:4010 °?? 

0807:4020 ?? 

0807:4030 °?? 

0807:4040 °?? 

0807:4050 ?? 

0807:4060 ?? 

> 


Figure 3.14b (Concluded) 


OS/2 could have been structured to provide automatic memory management 
features, but this would have removed some of the flexibility of the operating sys- 
tem. The ability to clean up memory and segregate usage expands the programmer’s 
access to more difficult problem-solving techniques. This is somewhat philosophi- 
cal and the actual implementation of memory allocation is left up to the individual 
user. It is, of course, essential for programs that push the limits of the physical 
system resources. 


3.2.5 Suballocating Memory 


The final memory management activity considered in this section is suballocation. 
This is the blocking of memory within an allocated segment and is best used if an 
application requests and frees small portions of memory at a frequent rate. It has the 
advantage that an allocation at the physical level is not needed. When a normal 
allocation occurs an LDT entry must be defined, a descriptor defined, physical 
memory located, and then the reverse when memory is released. The memory sub- 
allocation package (MSP) contains the calls 


@DosSubAlloc 
@DosSubSet 
@DosSubFree 


which allow the allocation and freeing of portions of a segment without incurring 
the system overhead. The services in the MSP simply keep track of which portions 
of the memory segment are in use. 
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Figure 3.15 presents a program that implements a memory suballocation 
operation. Basically, a segment with 16,385 bytes is allocated using @DosAllocSeg. 


PAGE 55,132 


TITLE SUBALLO -- Reallocate memory segment (suballo.asm) 


DESCRIPTION: This simple routine creates and suballocates 


a memory segment. 


include 
ENDIF 

-sall 
adgroup GROUP 
? 
STACK SEGMENT 
ab 
STACK ENDS 
; 
DATA 


SEGMENT 
msize aw 
msell aw 
mflag dw 
blk_ct dw 
mem wd db 
msizel dw 
moffset dw 
two aw 


e 


ENDS 


e 
DATA 


s 
CSEG SEGMENT 


sysmac.inc 


data 


PARA STACK 'STACK! 
256 dup ('STACK 


PARA PUBLIC 'DATA' 


16385 

? 
0000000000000000B 
16384, 8192 


Le es 'E', 'M', 'o', 'R', 


8192 
0 
2 


PARA PUBLIC 'CODE' 


assume cs:cseg,ds:dgroup 


0S21 PROC 


a 


@DosAllocSeg 


e 
a 


FAR 


push msell 


pop es 


mov di,O 
mov si,0 


push si 
push di 


pop di 
pop si 


mov ax,blk_ct[si] 
lea bp,mem_wd{di] 
mov di,moffset 


push si 
push di 


mov cx,8 
mov si,0O 


mov al,ds:[bp+si] 
mov es:[di],al 


inc si 
inc di 


loop LOOP2 


push di 


sub di,moffset 


ryt, 


msize,msel1,mflag 


The program should be run with CodeView. 


sbuffer size 
s;selector 
snot sharable 
block count 


§ rel S58 (BY tA ot Or te 


ssuballocated size 
:;offset to suballocated block 


sallocate segment 


tload allocated selector 
;pop to es register 


;initialize string offset 
zinitialize block count variable 
;preserve block count 
;preserve string offset 


;recall string offset 
s;recall block count 


sblock counter limit 
;string address 

tblock offset in segment 
#preserve block count 
;preserve block offset 


;count limit for string 
;index for string/buffer 


sload from string 
tload buffer 
;increment string 
sincrement block byte 


sblock offset + block count 
block count 


Figure 3.15 The program suballo.asm, which suballocates a 16,384-byte segment 
into an 8192-byte block. 
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emp di,dx ;check block limit 
pop di sblock offset + block count 
jl LOOP1 


mov ax,1l ;set suballocation flag 
mov mflag,ax sload 


@DosSubSet msell1,mflag,msize 


@DosSubAlloc msell1,moffset,msizel 


pop di ;recall string offset 
pop si ;recall block count 
add di,8 ;go to “SUBALLOC" 


add si,2 ;increment word index 
cmp si,two ;compare second loop 
push si ;preserve block count 
push di ;preserve string offset 
jle LOOP4 


@DosFreeSeg mseli 
@DosExit 1,0 
ENDP 


ENDS 
END 


Figure 3.15 (Concluded) 


Then 16,384 bytes are written in blocks of 8 bytes with “MEMORY ”. The serv- 
ice call 


@DosSubSet msell, mflag, msize 


initializes the segment for suballocation. Here msel1 is the allocated segment selec- 
tor; mflag is set to 1, indicating that a segment is being initialized; and msize is the 
original segment size. 

The call 


@DosSubAlloc msell, moffset, msizel 


returns an offset in the segment pointing to the start of the suballocated block whose 
size is msizel (in this case 8192 bytes). The parameter msel1 is, of course, the 
segment selector. 

Figure 3.16 illustrates the operation of this program based on CodeView out- 
put. In Figure 3.16a the initial load of the segment O06F:0000 to OO6F:3FFF is 
indicated. Here the end of the segment is demonstrated to contain“MEMORY ”. 
Next the suballocation is performed and in Figure 3.16b this is illustrated with 
“SUBALLOC” loaded up to address OOOF:2007. Note that there is a slight offset 
within the segment for the start of the suballocated block. This offset is 8 bytes and 
results in an overall shift by this number of bytes from the start of the segment. 
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= File Search View Run Watch Options Calls Trace! Go! SUBALLO. EXE 
Pe oe pet es eed © prensa at ne eg ge Og ee eee OT ed 
AX,Word Ptr [0002] 


AX 
AX,Word Ptr [0004] 
AX 


AX,Word Ptr [0000] 
AX 


00A7:0000 
AX,Word Ptr [0002] 
AX 

B82F00 AX, 0O02F 


>»d es:0x3ff0 
OO6F:3FFO 4D 
OO6F:4000 °?? 
OO6F:4010 ?? 
OO6F:4020 ?? 
OO6F:4030 7? 
OO6F:4040 ?? 
OO6F:4050 ?? 
OO6F:4060 ?? 
> 


Trace! Go! SUBALLO. EXE 


Pea ry ce Pigs ge en aie fer ee Bem oe cae Cig ie eee teghe eh Geen Ta 


A30400 Word Ptr [0004],AX 
Ai0200 AX,Word Ptr [0002] 
AX 


AX,Word Ptr [0004] 
AX 
AX,Word Ptr [0000] 
AX 


9AD000A700 O00A7: 0000 
A10200 AX,Word Ptr [0002] 


. 
e 
aaa a aa aaa 


OO6F:0070 53 SUBALLOCSUBALLOC 
>d es:0x1iff0 

OO6F: 1 FFO 3 SUBALLOCSUBALLOC 
OO6F: 2000 SUBALLOC....RY 
OO6F: 2010 MEMORY MEMORY 
OO6F: 2020 MEMORY MEMORY 
OO6F: 2030 MEMORY MEMORY 
OO6F: 2040 MEMORY MEMORY 
OO6F: 2050 MEMORY MEMORY 
OO6F: 2060 MEMORY MEMORY 

> 


(b) 


Figure 3.16 Facsimile CodeView output, illustrating (a) end of memory block for original 
allocation and (b) end of suballocated block with offset of 8 bytes. Cursor located in 
hidden portion of screen. (Courtesy of the Microsoft Corporation.) 
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3.3 MULTITASKING 


A major OS/2 enhancement (over DOS) is the ability to execute multiple tasks and 
segregate each task’s parameter space so that no mixing occurs. The OS/2 imple- 
mentation relies heavily on 80286 (and 80386) Protected Mode hardware features. 
Two threads, which exist as single entities with shared system resources, exist as 
stand-alone modules with their own system resources and can execute as separate 
tasks in Protected Mode. In this section we examine briefly the creation of threads 
and processes. 


3.3.1 Semaphores 


Before beginning our examination of task generation, however, it is necessary to 
consider synchronization. Assume, for example, that a given task depends on the 
outcome of a second task at some point in the first task’s execution. Clearly, when 
the first task is started it must be synchronized with the second task to ensure that 
the proper data become available when needed. If no requirement for synchroniza- 
tion exists, the two tasks can execute independently and are said to be asynchronous 
with respect to each other. 

A very important mechanism for achieving synchronization is the semaphore: 
RAM semaphores and system semaphores are considered in this book. A typical 
prescription for creating and accessing a RAM semaphore within a process (two 
threads) is as follows: 


Thread I 
@DosSemSet sem_handle 
call to 2nd thread 
~@DosSemWait sem_handle,—1l 
Thread 2 


activity to be synchronized 


@DosSemClear sem_handle 


Here the semaphore is set and the second thread called. Meanwhile the first thread 
waits for the semaphore to clear. When the second thread clears the semaphore, the 
first thread resumes execution. Only a handle, sem_handle, is used to pass informa- 
tion about the semaphore. This can be passed to a second independently compiled 
(or assembled) process via a shared memory area; however, in the illustration above 
it has been assumed that both threads are common to the same process and 
sem_handle appears in the process data area (as a double word). 
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System semaphores are used commonly between diverse processes and have 
the following general form: 


Data area 1 


Process 1 


no_excl dw 1 ;no exclusive 
aseml db ‘\SEM\SDAT.DAT,0 ;semaphore name 
sem_hdll dd 0 ;handle 

no_to dd -1 ;no time out 
@DosCreateSem no_excl, sem_hdll, aseml 
@DosSemSet sem_hdll 


call to execute 2nd process 
@DosSemWait sem_hdll,no_to 


Data area 2 


Process 2 


aseml db ‘\SEM\SDAT.DAT’,0 ;semaphore common name 
sem_hdll dd 0 shandle 

no_to dd -1 ;no time out 
@DosOpenSem sem_hdll,aseml 


activity to be synchronized 


@DosSemClear  sem_hdll 


We see that the contrast between the two types is that system semaphores require a 
name and hence can be accessed from disjoint segments. RAM semaphores simply 
require a common handle. Fast-safe RAM semaphores are used by dynalink librar- 


ies. 


3.3.2 Creating a Thread 


Figure 3.17a is the flowchart for a program that generates two threads using RAM 
semaphores for synchronization. Figure 3.17b shows the actual code used in this 
process. The first thread clears the screen, writes message msg_p0 to the display, 
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SETUP 
DATA 


CLEAR 
SCREEN 


WRITE TTY 
MESSAGE #1 


BEEP #1 


SET 
SEMAPHORE 


CREATE 
THREAD #2 


BEEP #2 


WRITE TTY 
MESSAGE #2 


CLEAR 
SEMAPHORE 


WAIT CLEAR 
SEMAPHORE 


Figure 3.17a Flowchart for a program 
that generates two threads using RAM 


EXIT ee 
semaphores for synchronization. 
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TITLE CKTH1 -- Check thread generation (ckth1.asm) 


generated. 


=e te VO NE MO 


-sall 


-xlist 
INCL_BASE equ 1 
include os2def.inc 
include bse.inc 
-list 
, 
errorl macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


agroup GROUP data 


‘ 

STACK1 SEGMENT WORD STACK 'STACK1' 
dw 1024 dup(?) 

stklend equ 

STACK1L ENDS 


, 

STACK SEGMENT WORD STACK 'STACK' 
dw 1024 dup(?) 

STACK ENDS 


; 
DATA SEGMENT WORD PUBLIC 'DATA' 


, 
result dw 0 
action equ 1 


; 

msg_pO db 'This is the main OS/2 thread' 
dab ODH 
db OAH 


lmsg_p0O equ $-msg_pO 
msg_pl db 'This is a separate OS/2 thread! 
db 


db 
lmsg_pl equ 


DESCRIPTION: This routine verifies that a thread is 


Stack for threadl1 


*Stack for main program 


:Exit code from main 
sAction code from main 


;Carriage return 
;Line feed 
;Length message zero 


;Carriage return 
;Line feed 
;Length message one 


msg_p2 db ‘An error occurred on thread open' 


ODH 
db OAH 


lmsg_p2 equ $-msg_p2 
viohdl equ 0 


a 
freq 
duration 


e 
’ 
e 
s 
° 
’ 
° 
e 
e 
e 


threadl 


;Carriage return 
;Line feed 

;Length message two 
:Video handle 


75000 Hz 
7500 msec 


sAddress threadl 


Figure 3.17b Program illustrating two threads that use RAM semaphores for 
synchronization. The speaker is beeped and a message written. 
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stk_adrl 
threadID 
thd1_exi 


thd_sem1 
sem_hdll 
no_to 

; 

tr 

le 

br 


; 
DATA 


‘ 
CSEG 


0S21 


e 
c 


ERROR11: 


CONT: 


O0S21 


‘ 
threadl 


? 
threadl 


cls 


t_code 


ENDS 


stklend 


Lt) 
thd_sem1 
=1 


SEGMENT WORD PUBLIC 'CODE' 


assume 
PROC FAR 


call cls 


@VioWrtTTY 
errorl 


@DosBeep 
errorl 


@DosSemSet 
errorl 


@DosCreateThread 


errorl 

jmp CONT 
@VioWrtTTY 
jmp ENDD 


@DosSemWait 


cs:CSEG,ds:dgroup,ss: STACK 


msg_p0,1msg_p0,viohdl 


freq,duration 


sem_hdli 


msg_p2,lmsg_p2,viohdl 


sem_hdli,no_to 


@DosExit action, result 


ENDP 


PROC FAR 
@DosBeep 
@viowrtTTY — 


@DosSemClear 


freq,duration 
msg_p1,1msg_p1,viohdl 


sem_hdll 


@DosExit action,thd1_exit_code 


ENDP 
PROC NEAR 


@vioScrollUp 


7End STACK1 
sthreadi I.D. 
:Thread 1 exit code 


;Semaphore threadl 
;Address thd_seml 
7No time out 


;Top row screen 

sLeft corner 

7;Bottom row 

;Right corner 

:Number blanked lines 
7Blank attribute 


;Write message one 


7;Beep speaker 


Set RAM semaphore 


prgmadd, threadID,stk_adrl 


;Write error message 


;Wait for semaphore clear 


;Exit 


;Beep speaker 
*Write message two 
;Clear semaphore 


;Exit threadl 


tr,1lc,br,rc,no_line,blank,viohdl 


Figure 3.17b (Continued) 
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Figure 3.17b (Concluded) 


beeps the speaker, sets a semaphore, turns on thread1, waits for the semaphore to 
clear, and exits the process. The second thread, thread1, beeps the speaker, writes 
msg _ pl to the display, clears the semaphore, and exits thread1. Synchronization is 
needed because both threads access the display and collisions will result if they run 
asynchronously. 

Figure 3.18a is the flowchart for a program that generates random boxes to the 
screen, one at a time. The program creates a box of random size (again, in our 
constraint of 200 x 200 pixels for CGA mode), erases the box, and continues (cre- 
ating and erasing boxes). The box creation occurs as a separate thread running 
asynchronously from the main thread. The main thread, once having turned on the 
box generator thread, simply waits for a keyboard input to terminate the process. 
Both threads run as part of the same process. 

The program code is presented in Figure 3.18b, where the main thread clears 
the screen, sets CGA mode and clears the screen again, locks the display and gets 
a selector to the physical screen buffer, beeps the speakers, turns on thread1, and 
waits for a keyboard input. Following a keyboard input, the screen is unlocked, 
standard mode resumed (80 x 25), the screen cleared again, and the process exited. 

Meanwhile the second thread, once started, first beeps the speaker and then 
enters an infinite loop. Within this loop a set of random box corners are generated 
and the box drawn on the display, as indicated above, with a call to boxx. The pixel 
(pel) attribute is set to unity for this call. Next, the box is erased by repeating the 
call with the pixel attribute set to zero. 

In general, the instruction 


@DosExit action, result 


will stop both threads from executing when called from the parent. This happens 
only in response to the keyboard input, which is sensed using @KbdStringIn. 

Figure 3.19 contains the support routines used by the box generating program: 
boxx, clsCGA, wdot, lineh, and linev. Note that some of the routines are slightly 
different from their counterparts given in GRAPHLIB.LIB (boxx is FAR, for ex- 
ample). Also, note that the second thread procedure is of distance attribute FAR 
even though it is defined within the same segment as the main thread. This allows 
the second thread to pass a full 32-bit address for its entry point. Multiple threads 
within the same process should be used when the task in question is reasonably 
simple and can be modularized within the same segment. 


Sec. 3.3 Multitasking 135 


SETUP 
DATA 


CLEAR 
SCREEN 


SET CGA MODE AND 
CLEAR SCREEN 


LOCK SCREEN 
CONTEXT 


GET SELECTOR 
PHYSICAL BUFFER 


BEEP #1 


CREATE 
THREAD 


BEEP #2 


WRITE TTY 
MESSAGE #2 


CLEAR 
SEMAPHORE 


KEYBOARD 
HESITATE 


UNLOCK 
SCREEN 


- SETSTD 


CLEAR 
SCREEN 


Figure 3.18a Flowchart for a program 
that generates single random boxes 


EXIT using multiple threads. 
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TITLE UNOS251 - This is the calling OS/2 program (UNOS251.ASM) 


me %e@ NO Me VO NO 


- 8087 
EXTRN 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


7 


e 
’ 


° 
e 


dgroup 
; 
STACK1 


stkliend 
STACK1 


a 
STACK 
STACK 
; 
DATA 


v 
viohdl 
result 
action 
actionl 
tr 
le 
br 
re 
no_line 
blank 

c 
CGAm 
lmodeE 
typeCGA 
colCGA 
txtcCGA 
txtrcGa 
hrcCGaA 
vrCGA 

ce 
STDm 
lmodes0 
types0 
cols0o 
txtcs80 
txtrso 


DESCRIPTION: This program "single" random plots boxes in protected 
mode. Graphics mode 05H is used to display the boxes. This routine 
employs multithreading to generate the boxs which are 

generated randomly (100 boxes in square 200 x 200). 


boxx: FAR, C1SCGA: FAR 


viohdl,CGAm, lmodeE, typeCGA, colCGA 

txtcCGA, txtrCGA, hrCGA, vrCGA, STDm, lmode80, type80,co180 
txtc80,txtr80,hr80,vr80,waitf,dstat, PVBPtr1,bufst1,buflenl,physell 
MASK1 , MASK11, OF FSET1, four, xx, dummy, two, xxx, eighty, row,col 


address1,x,y,xb,xe,ye, yb, Xxxx 


-sall 

-xlist 
INCL BASE equ 1 
include os2def.inc 
include bse.inc 

-list 

GROUP data 

SEGMENT WORD STACK 'STACK1' 

dw 1024 dup(?) 

equ $ 

ENDS 

SEGMENT WORD STACK 'STACK' 

dw 1024 dup(?) 

ENDS 

SEGMENT WORD PUBLIC 'DATA' 

equ 0 

aw 0 

equ 1 

equ 0 

aw 0 

dw 0 

dw 23 

aw 79 

aw 25 

aw 0007H 

label FAR 

dw 12 

db 00000111B 

ab 2 

aw 40 

dw 25 

dw 320 

aw 200 

label FAR 

dw 12 

ab 00000001B 

ab 4 

dw 80 

dw 25 


Stack for thread 


;Required video handle 
;Completion code 
;Terminates current thread 
;Thread termination action 
:Top row screen clear 
Left column screen clear 
Bottom row screen clear 
*Right column screen clear 
sNumber lines scrolled 
:Blank character pair 


;Video mode structure-CGA 
;Structure length 

;Mode identifier 

sColor option-Mode 5 

;text characters/line-ignore 
;text lines-ignore 
shorizontal resolution 
svertical resolution 


;Video mode structure-80x25 
;Structure length 

:Mode identifier-Mode 3+ 
:Color option 

;text characters/line 

stext lines 


Figure 3.18b Main program for the “single” random box routine. 
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hrs0 dw 
vr8s0 aw 


kbd_buf db 
lkbd_buf dw 
iowait daw 
kbdhdl equ 


waitf 
dastat 


PVBPtr1 
bufstl1 

buflenl 
physell 


MASK1 
MASK2 
MASK22 
MASKi1 dw 
OFFSET1 dw 
four aw 
xX dw 
dummy dw 
two dab 
XXX ab 
eighty dw 
zero dw 
one dw 
row dw 
col dw 
address1 
rndret db 


threadID 

XXXX 
thd1_exit_code 
thd_seml 
sem_hdll 

no_to 

freq 

duration 


720 
400 


80 


shorizontal resolution 
svertical resolution 


;Keyboard buffer 


$-kbd_buf ;Length keyboard buffer 


.¢) 
0 


1 
2 


FAR 


;Wait for CR 
;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 


OB8000H ;Start physical address 
4000H ;Buffer length 


& NN 
fo] 
°o 
(2) 
8 


ae ae oy 


VN OV OV oN 


;0S/2 screen buffer selector 


;PEL byte mask 

;PEL byte mask-~--do 
;PEL byte mask--undo 
;Odd/even row mask 
;Odd row buffer offset 


;PEL attribute parameter 
780287 dummy "pop" 


;Output value 


;row 
;column 

;Address screen dot 
srandom no. returned 


;Box col parameter 
;Box row parameter 
;Start column 

7End column 

*Start row 

7End row 


srandom seed 
saddress thread 

send of thread stack 
sthread ID 

sbox corner buffer 


sthread1 exit code 


:Semaphore threadi 
;Address thd_seml 

:No time out 

:frequency beep in Hz 
;duration beep in millisec 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK 


PROC 


 ¢all cls 


FAR 


;Clear screen 


Figure 3.18b (Continued) 


137 


138 Chap. 3 


Memory Management and Multitasking with Assembler 


@VioSetMode CGAm,viohdl ;Set CGA graphics mode 


call clsCGA ;Clear CGA screen 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 
@VioGetPhysBuf PVBPtri1,viohdl 
push physell 

pop es 


7Get physical buff sel 
;Save selector 

s:Load selector into es 
@DosBeep 


freq,duration ;Beep speaker 


@DosCreateThread prgmadd, threadID,stk_adrl 


@KbdStringIn kbd_buf,1lkbd_buf, iowait,kbdhdl 


shesitate 


@VioScrUnlock viohdl 
@VvioSetMode STDm,viohdl 
call cls 


@DosExit action,result 


;Unlock screen 


780 x 25 alpha mode 


;Terminate process 


ENDP 


PROC 


@vioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


ret 


NEAR 


ENDP 


PROC 


Mov 
mov 
mov 
mov 
mov 
mov 
ret 


NEAR 
bh,0 
bl,al 
xb, bx 
bh,0 
bl,ah 
xe,bx 


ENDP 


PROC 


mov 
mov 
mov 
mov 
Mov 
Mov 
ret 


NEAR 
bh,0O 
bl,al 
yb, bx 
bh,0 
bl,ah 
ye,bx 


ENDP 


PROC FAR 


@DosBeep 


mov 
mov 


lea 


freq,duration 


ax,one 
rndl1,ax 


bp, Xxxx 


cx, 4 
di,o 


;Clear upper register half 
zal = start 

;Load xb less than 199 
;Clear upper register half 
;ah = end 

;Load xe less than 199 


;Clear upper register half 
7al = start 

;Load yb less than 199 
;Clear upper register half 
;ah = end 

;Load ye less than 199 


;Beep speaker 


;random seed 
;load r.n. parameter 


74 byte buffer 
zunterminated loop 


sbox corner count 
7r.n. memory index 


Figure 3.18b (Continued) 
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Sec. 3.3 


Multitasking 


call ldmem 
mov al,rndret 


mov ds: [(bp+di]),al 


inc di 
loop LOOPOO 


mov al,ds: [bp] 
mov ah,ds: [bp+1) 
cmp ah,al 
jne EELSE1 
mov al,170 
mov ah,180 
call xload 
jmp IIF1 


cmp ah,al 

jle ELSE1 
call xload 
jmp IIF1 


mov bl,al 
mov al,ah 
mov ah,bl 
call xload 


mov al,ds: [bp+2] 
mov ah,ds: (bp+3] 
cmp ah,al 
jne EELSE2 
mov al,170 
mov ah,180 
call yload 
jmp IIF2 


cmp ah,al 

jle ELSE2 
call yload 
jmp IIF2 


mov bl,al 
mov al,ah 
mov ah,bl 
call yload 


push xb 
push xe 
push yb 
push ye 
mov al,MASK2 
mov MASK1,al 


call boxx 


pop ye 
pop yb 
pop xe 
pop xb 
mov al,MASK22 
mov MASK1,al 


call boxx 
jmp LOOPO 


@DosExit 
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;load random memory values 
;move r.n. into register 
;save r.n. in memory 
;increment r.n. memory index 


jlst r.n. value 

s;2nd r.n. value 

;check 2nd different than lst 
;jump if not equal 

;move in arbitrary value 1.t. 200 
smove in different value 

z;load xe and xb 


;check 2nd less than lst 
;jump if less or equal 
7if g.t. calculate xb and xe 


72nd g.t. lst -- swap 
;Sswap 

7reload 

;calculate xe and xb 


73rd r.n. value 

74th r.n. value 

;check 3rd different than 4th 
;jump if not equal 

;move in arbitrary value 1.t. 200 
;move in different value 

;load ye and yb 


;check 4th less than 3rd 
;jump if less or equal 
sif g.t. calculate yb and ye 


73rd g.t. 4th -- swap 
;swap 

;reload 

;calculate yb and ye 


;preserve box parameters 


;PEL value set 
s;load dummy 


swrite box 


;recall box parameters 


7PEL value black 
;load dummy 


sundo box 


;jump unterminated loop 


action1,thd1_exit_code 


Figure 3.18b (Continued) 
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threadi ENDP 


ldmem PROC NEAR 


’ 


push ax 
push bx 
push dx 


mov 
mov 
mov 
mul 
mov 
clc 
add 
adc 
mov 
div 
mov 
mov 


ax, 0 

ax, rndl 
bx, 2053 
bx 

bx, 13849 


ax, bx 
dx,0 
bx, OF FFFH 
bx 

ax, ax 
rndi,ax 


zload upper multiplicand 
sload previous r.n. 
smultiplier 


sload additative constant 


sadd lower order result 
;add carry if needed 
zload 2(16)-1 
s;calculate modulo 

tmov remainder into ax 
;save r.n. 
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mov ;scale r.n. less than 200 
mov :clear upper dividend 
div 

mov ssave al 

mov rndret,al ;returned value byte 
pop dx 

pop bx 

pop ax 

ret 

ENDP 


ENDS 
END 


Figure 3.18b (Concluded) 


3.3.3 Creating Another Process 


When multiple processes are to be synchronized the system semaphores are appro- 
priate. System semaphores provide a common link between the two processes 
through the semaphore name. If RAM semaphores are used, the semaphore handle 
must be shared with a common data element. Figure 3.20a illustrates a program that 
generates two processes using system semaphores for synchronization. The sema- 
phore name must be zero terminated and preceded by 


‘\SEM\...’ 
In Figure 3.20b we illustrate this naming with a semaphore called 
‘\SEM\SDAT.DAT’, 0 


and given the variable name asem1. 
The second process called by the program in Figure 3.20b is OS2P2.EXE, as 
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TITLE NNOS252 - Supplemental routines for box plotting (NNOS252.ASM) 


=e @ =e %e te Te TE Me 


=e 


EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
, 
CSEG 
PUBLIC 


Figure 3.19 Associated support routines for the “single” random box program. 


DESCRIPTION: These routines set up box plots in CGA mode. 
mode 05H is used to display the box. This set of routines 
is called by box plotting main routine. 


destroyed depending on MASK1 value. 


-sall 


-xlist 


INCL_BASE equ 1 
include os2def.inc 
include bse.inc 


-list 


viohdl : WORD 


CGAm: FAR, 1modeE: WORD, typeCGA: BYTE 


COl1CGA: BYTE, txtcCGA: WORD, txtrCGA: WORD, hrCGA: WORD, vrCGA: WORD 

STDm: FAR, lmode80:WORD, type80: BYTE, col80: BYTE, txtc80:WORD, txtr8s0:WORD 
hr80:WORD, vr80:WORD 

waitf:WORD, dstat: BYTE, PVBPtr1: FAR, bufst1:DWORD 

buflen1: DWORD, physel1: WORD, MASK1: BYTE, MASK11: WORD, OFFSET1: WORD 

four: WORD, xx: WORD, dummy: WORD, two: BYTE, xxx: BYTE, eighty: WORD 
row:WORD,col:WORD, address1:WORD,x:WORD, y: WORD, xb: WORD, xe: WORD 

yb: WORD, ye: WORD 


SEGMENT WORD PUBLIC 


boxx, C1SCGA 


assume cs:CSEG 


PROC FAR 


The boxes are created or 


xb = x-begin,xe = x-end,yb = y-begin,ye = y-end 


push ax 
push bx 
push cx 
push dx 


mov ax,xb 

cmp ax,xe 

jl ELSE10 
xchg ax,xe 
mov xb,ax 


mov ax,yb 

cmp ax,ye 

jl ELSE11 
xchg ax,ye 
mov yb,ax 


mov ax,yb 
mov y,ax 
call lineh 
mov ax,ye 
mov y,ax 
call lineh 
mov ax,xb 
mov x,ax 
call linev 
mov ax,xe 
mov x,ax 
call linev 


7;Check xb 1.t. 


;Swap xb and xe 


;Check yb 1.t. 


:Swap yb and ye 


:Top box line 


;Draw top horizontal line 


xe 


ye 


Bottom box line 


;Draw bottom horizontal line 


:Left box line 


:Draw left vertical line 
?Right box line 


;Draw right vertical line 
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pop dx 

pop cx 

pop bx 

pop ax 
; 

ret 


boxx ENDP 


e 


e 
clsCGA 


e 
’ 


PROC FAR 


@vioScrLock waitf,dstat,viohdl 
@VioGetPhysBuf PVBPtri1,viohdl 
push physeli 

pop es 


mov bp,0 
mov al,0O 


mov es: [(bp],al 
inc bp 

cmp bp, 1F3FH 
jle Dol 


mov bp, 2000H 
mov al,0 


mov es: [(bp],al 
inc b 

cmp bp, 3F3FH 
jle Do2 


@VioScrUnLock viohdl 


ret 
ENDP 


PROC NEAR 


(col,row) = (x,y) 


push ax 
push bx 
push cx 
push ax 
push bp 


fild four 
fild col 


fprem 

fistp xx 
fistp dummy 
mov al,3 

mov bl,byte ptr xx 
sub al,bl 
mov ah,0O 

mul two 

mov cl,al 
mov al,MASK1 
shl al,cl 
mov xxx,al 


mov ax, row 
shr ax,1 
mov dax,0 
mul eighty 


7;Lock screen context 
;Get physical buffer 
;Screen selector 
;Load extra segment 


Start offset zero 
;Zero attribute-clear 


;Clear byte 

;Check end ist buffer 

;Offset 2nd buffer-odd 
;Zero attribute-clear 

;Clear byte 


7;Check end 2nd buffer 


Unlock screen context 


;Load stack with 4 
*;ST = col, ST(1) = 
;Modulo 
;Store remainder in xx 
7Pop stack 


4 


7(3 - col % 4) 
7Clear upper multiplicand 


;Shift value for PEL 
;PEL color mask 
7Shift to correct PEL 
;Store buffer value 


;Begin address calculation 
;Divide row by 2 
;Clear upper multiplicand 


Figure 3.19 (Continued) 
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mov bx,col 

shr bx,1 

shr bx,1 

add ax,bx 

mov addressl,ax 

mov ax, row 

and ax,MASK11 

cmp ax,0 

jle ELSE1 
mov ax,addressl 
add ax,OFFSET1 
jmp IF11 


mov ax,addressl 


mov bp,ax 
mov al,xxx 


cmp al,0O 

je ccc 
or es: [bp],al 
jmp DDD 


mov es:[bp],al 


pop bp 
pop dx 
pop cx 
pop bx 
pop ax 


ret 
ENDP 


PROC NEAR 


y = row position, xb = begin, xe 


push ax 
push bx 
push cx 
push dx 


mov ax,y 

cmp ax,199 

jg LINE1 
mov row,ax 
jmp LINE2 


mov ax,180 
mov row,ax 


mov ax,xb 


mov col,ax 
push ax 
cmp ax,319 
jle LINE3 
mov ax,319 
mov col,ax 


call wdot 
pop ax 
inc ax 
cmp ax,xe 
jle po10 


;Convert column value to bytes 


;offset in ax 

Save offset base 
;Check even/odd row 
:;Look for bit 0 set 


s;add odd buffer offset 


sscreen buffer address 
sAttribute value for dot 


;check PEL black (0) 


sWrite dot 


7;Clear PEL 


= end 


sEstablish row for wdot 
scheck row l1.t. 199 
:jump if greater 

sload "row" 


sload arbitrary value l1.t. 199 


sload "row" 
:Establish start column 
7Save column value 


;check col less than 319 
;jump if l.t.e. 319 


;if greater load arbitrary value 


sload "col" 


;Write dot (col,row) 
7;Recall column 
sIncrement column 


;Check end horizontal line 


e 
, 


Figure 3.19 (Continued) 
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pop dx 
pop cx 
pop bx 
pop ax 


ret 
ENDP 


PROC NEAR 


x = col position, yb = begin, ye = end 


push ax 
push bx 
push cx 
push dx 


mov ax,x 
cmp ax,319 
jg LLINE1 
mov col,ax 
jmp LLINE2 
LLINE1: 
mov ax,319 
mov col,ax 


LLINE2: 
mov ax,yb 
D020: 
mov row,ax 
push ax 
cmp ax,199 
jle LLINE3 
mov ax,199 
mov row,ax 
LLINE3: 
call wdot 
pop ax 
inc ax 
cmp ax,ye 
jle bDo20 


pop dx 
pop cx 
pop bx 
pop ax 


ret 
ENDP 


ENDS 
END 


sEstablish column for wdot 
s;check col 1.t. 319 

;jump if greater 

sjload "col" 


;greater therefore arbitrary value 
sload "col" 


e 
’ 


:Establish start row 


;Save row value 

:check row value g.t. 199 

;jump if less 

:greater therefore arbitrary value 
sload "row" 


;Write dot (col, row) 
7;Recall row 

sIncrement row 

;Check end vertical line 


° 
e 
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Figure 3.19 (Concluded) 


specified under prgrm_nm in the parameter list for @DosExecPgm. The process 
indicated in Figure 3.20b clears the screen, writes msg _p0 to the display, creates a 
system semaphore with handle sem_hdl1 and name SDAT.DAT, beeps the speaker, 
sets the semaphore, and turns on the second process. Following this, the process 
waits for the system semaphore to clear and then terminates both the second proc- 


Sec. 3.3 Multitasking 145 


SETUP 
DATA 


CLEAR 
SCREEN 


WRITE TTY 
MESSAGE 


CREATE 
SEMAPHORE 


BEEP #1 


SET 
SEMAPHORE 


CREATE 
PROCESS #2 


PROCESS #2 


WAIT CLEAR 
SEMAPHORE 


KILL 
PROCESS #2 


Figure 3.20a Flowchart for program 
that generates two processes using 


EXIT 
system semaphores. 


ess and itself. Note that this main process accesses the screen at several points (cls 
and @VioWrtTTY). 

Figure 3.21a illustrates the flowchart for the child process, 
OS2P2.ASM, turned on by the program in Figure 3.20b. The supporting code is 
shown in Figure 3.21b. The common semaphore name, ‘\SEM\SDAT.DAT’, 0, is 
again defined by a variable asem1 (not related by symbol to the asem1 appearing in 
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TITLE CKPR1 -- Check thread generation (ckprl.asm) 


generated. 


=e we te TE MS 


-sall 


=e 


-xlist 


INCL_BASE equ 1 
include os2def.inc 
include bse.inc 


elist 
errorl macro 

local ERROR12 

or ax,ax 

jz ERROR12 

jmp ERROR11 

ERROR12: 

endm 


s 


dgroup GROUP data 


s 
STACK SEGMENT WORD 


STACK "STACK' 


dw 1024 dup(?) 


STACK ENDS 


’ 
DATA SEGMENT WORD PUBLIC 'DATA' 


result (¢) 
action 1 
msg_po 
ODH 
OAH 


lmsg_pO equ 


e 
viohdl equ 


‘ 
freq 
duration 


™e se te Oe te 


$-msg_p0 


'This is the main OS/2 thread' 


'\SEM\SDAT. DAT’, 0 
0 


DESCRIPTION: This routine verifies that a process is 


;Stack for main program 


7;Exit code from main 
sAction code from main 


;Carriage return 
;Line feed 
;Length message zero 


:Video handle 


74000 Hz 
7500 msec 


7no exclusive 

;Name system semaphore 
;Address thd_seml 

7No time out 


=e “eo “8 Se te Ne 


;Top row screen 

;Left corner 

Bottom row 

;Right corner 

s;Number blanked lines 
7Blank attribute 


Figure 3.20b Program that generates two processes using system semaphores. 
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obj_name_buf 
lobj_name_buf 
async 

argptr 

envptr 

pid 


prgm_nm 


° 


, 
DATA ENDS 


10 dup(?) 
$-obj_name_buf 


OS2P2.EXE',0 


CSEG SEGMENT WORD PUBLIC 'CODE'! 


assume 
OS21 PROC FAR 


call cls 


@VioWrtTTY 
errorl 


@DosCreateSem 
errorl 


@DosBeep 


@DosSemSet 
errorl 


@DosExecPgm obj_name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 


errorl 


@DosSemWait 


e 
e 


cs:CSEG,ds:dgroup,ss:STACK 


msg_p0,1lmsg_p0,viohdl 


no_excl,sem_hdl1,aseml 


freq,duration 


sem_hdll 


sem_hdll1,no_to 


@DosKillProcess 1,pid 


e 
ERROR11: 


@DosExit action, result 


0S21 ENDP 


, 


cls PROC NEAR 


° 
’ 


@VioScrollUp 


ret 
ENDP 


ENDS 
END 0S21 


;Process name buffer 
slength buffer 
sasynchronous operation 
;pointer arguments 
;environment pointer 
;process ID 


sprocess name 


;Clear screen 


;Write message 


;Create system semaphore 


;Beep speaker 


;Set semaphore 


;Create child process 


;Wait for semaphore clear 


;Terminate child process 


;Exit 


;Clear screen 


tr,lc,br,rc,no_line,blank,viohdl 


Figure 3.20b (Concluded) 
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OPEN 
SEMAPHORE 


WRITE TTY 
MESSAGE 
CLEAR 
SEMAPHORE 


Figure 3.2la Flowchart for a child 
process, illustrating synchronization 
using system semaphores. 


the parent). This child process opens the semaphore, beeps the speaker, writes a 
message msg _p1 to the display, and clears the semaphore. The process then termi- 
nates itself. Synchronization is needed because both processes access the display. 

This very brief example presents the use of multiple processes that must be 
synchronized. Earlier we used flags in a common data area to accomplish this with 
the program that displayed 100 random boxes at once. The use of semaphores is a 
more formal and elegant way to achieve synchronization and does not require 
a constant polling of the flag to check for process completion. The system does this 
for us. 
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PAGE 55,132 
TITLE OS2P2 -~ Check thread generation (os2p2.asm) 


se we te te & 


=e 


e 
’ 


errorl 


DESCRIPTION: This routine verifies that a 2nd process is 
generated. It uses semaphores for synchronization. 


~sall 


-xXlist 
INCL_BASE equ 1 
include os2def.inc 
include bse.inc 
-list 


macro 
local ERROR12 
or ax,ax 
jz ERROR12 

jmp ERROR11 


ERROR12: 


? 
dgroup 
STACK1 


STACK1 


i 
DATA1 


a 
result 
action 


msg_pl 


lmsg_pl equ 


a 
viohdl 


freq 


endm 
GROUP datal 
SEGMENT WORD STACK 


dw 1024 dup(?) 
ENDS 


‘STACK1' 


SEGMENT WORD PUBLIC 'DATA1' 


dw 0) 
1 


;Stack for 2nd process 


:Exit code from process 
sAction code from process 


'This is a separate OS/2 process’ 


ODH 
OAH 
$-msg_p1 


equ 


duration 


me "Oe ~e MO ME 


;Carriage return 
;Line feed 
s;Length message one 


:Video handle 


75000 Hz 
7500 msec 


Semaphore parameters 


'\SEM\SDAT. DAT! , 0 
0 


=1 


;Semaphore name 
;Address thd_seml 
:No time out 


SEGMENT WORD PUBLIC 'CODE' 


assume 
PROC 


@DosOpenSem 


errorl 


@DosBeep 


errorl 


Figure 3.21b Child process, illustrating synchronization using system semaphores. 


cs:CSEG,ds:dgroup,ss:STACK1 
FAR 


sem_hdll1,aseml 


freq, duration 


;Open system semaphore 


;Beep speaker 
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@VioWrtTTY msg_p1,1lmsg_p1,viohdl ;Write message 
errorl 


@DosSemClear sem_hdll ;Clear semaphore 


ERROR11: 
@DosExit action,result ;Exit process 


0S21 ENDP 
CSEG ENDS 
END 


Figure 3.21b (Concluded) 


3.4 INTERPROCESS COMMUNICATIONS 


We have seen examples of interprocess communication (IPC) using shared memory 
and semaphores. OS/2 has three additional mechanisms for achieving such commu- 
nication: pipes, queues, and signals. Signals basically act like a hardware interrupt 
and tend to reflect rather specialized interprocess communications [5]. We only 
mention them. The dominant mechanisms we focus on in this book are the remain- 
ing four. Synchronization is a major requirement for processes competing for serial 
mechanisms [6]. OS/2 solves this problem in a number of ways. 


3.4.1 Pipes and Queues 


A flowchart for a parent program that passes messages via pipes is illustrated in 
Figure 3.22a. The code associated with the parent is presented in Figure 3.22b. This 
program employs several IPC mechanisms in addition to pipes: semaphores, for 
achieving synchronization, and shared memory, for passing the pipe handle and 
message length. First the screen is cleared with a call to cls. Next, the shared seg- 
ment is created and this segment is arbitrarily large (512 words). The call to 
@DosMakePipe creates the pipe with a read handle, read_hdl, and a write handle, 
write_hdl. The parameter pflag specifies the pipe length in bytes. 

Note that a pipe is anonymous in this context and serves simply as a high- 
speed buffer area with no name. A system semaphore is created, the speaker beeped, 
the message msg_p0 written to the pipe buffer using write_hdl, the semaphore set, 
and a child process executed. The parent then waits for the child to execute and 
clear the semaphore before it terminates the child and exits. 

Figure 3.23a presents the flowchart for the child process. Figure 3.23b contains 
the code for this process. Initially, the child opens the semaphore, beeps the speaker, 
and gets a selector to the shared segment. This shared segment is used to obtain a 
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SETUP 
DATA 


CREATE SHARED 
SEGMENT 


CREAT 
PIPE 


PIPE READ HANDLE IN 
SHARED SEGMENT 


CREATE 
SEMAPHORE 


WRITE MESSAGE 
TO PIPE 


SET 
SEMAPHORE 


CREATE 
CHILD 


CHILD 
PROCESS 
WAIT CLEAR 
SEMAPHORE 


KILL 
PROCESS 


Figure 3.22a Flowchart for a main 
program that examines pipes for 


EXIT ° ea 
interprocess Communication. 
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TITLE PIPEST -- Check pipe generation (pipest.asm) 


generated. 


=e se TE Te & 


-sall 


=e 


-xlist 
INCL_BASE equ 1 
include os2def.inc 
include bse.inc 
-list 
errorl macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


adgroup GROUP data 
; 
STACK SEGMENT WORD STACK 
dw 1024 dup(?) 
STACK ENDS 


’ 


DATA SEGMENT WORD PUBLIC ‘DATA’ 


‘STACK’ 


result dw 0 


action equ 1 
msg_pO db 'This is the OS/2 pipe message' 


db ODH 
db OAH 
lmsg_pO equ $-msg_po 
viohdl equ 0 
freq dw 4000 
duration dw 500 
; Semaphore 1 parameters 
no_excl dw 1 
aseml db '\SEM\SDAT. DAT! ,0 
sem_hdli dd 0 
no_to dd “1 
tr dw 0 
le dw fe) 
br dw 23 
re dw 79 
no_line dw 25 
blank aw 0007H 


DESCRIPTION: This routine verifies that a pipe is 


;Stack for main program 


;Exit code from main 
:Action code from main 


;Carriage return 
;Line feed 
;Length message zero 


:Video handle 


34000 Hz 
7500 msec 


sno exclusive 

;Name system semaphore 
;Address 

:No time out 


om am OF om an an > 


;Top row screen 

Left corner 

;Bottom row 

;Right corner 

sNumber blanked lines 
;Blank attribute 


me te “0 Te Be VE 


Process Created Parameters 


Figure 3.22b Pipe main program. 
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obj_name_buf dd 
lobj_name_buf dw 


10 dup(?) 
$-obj_name_buf 


async dw 1 
argptr dw .¢) 
envptr dw 0 
pid dw ? 
dw ? 
prgm_nm db 'PIPECL.EXE',0 
¢ 
; em one Ome ene Oe oe Om me oe oe oe oe oD Om Om oe oe es oe so om oe ee ee 
; Pipe Parameters 
; > ED Gee Coe GTP GED CUD CUD EP GU SEF GED GUD GED UE ORE GED GED OED ERD GED Gu” tn GD GND GD eae ane ame aon ane 
read_hdl dw ? 
write_hdl dw ? 
pflag dw 256 
bytes written dw 2 


eo =e te te Te TO 


’ 

msize dw 512 
msell dw ? 
shrname db 


e 

’ 

H = om 2 om © ee oe Oe oe Om Om 0 Oe 0 om Om Oe 0 on om 0 oe oe oo 
e 


zero dw 0 

one dw 1 

? 

DATA ENDS 

; 

CSEG SEGMENT WORD PUBLIC ‘CODE! 


assume cs:CSEG,ds:dgroup,ss:STACK 
0S21 PROC FAR 
? 
call cls 
; 
@DosAllocShrSeg msize,shrname,msell 
errorl 
push msell 
pop es 


mov bp, zero 


=e 


@DosMakePipe read_hdl,write_hdl,pflag 
errorl 

mov ax,read_hdl 

mov es: [bp+2],ax 


=e 


no_excl,sem_hdll1,asem1l 


@DosCreateSem 
errorl 
? 
@DosBeep freq,duration 


oe 
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;Process name buffer 
slength buffer 
sasynchronous operation 
;pointer arguments 
zenvironment pointer 
;process ID 


;process name 


;Pipe read handle 
;Pipe write handle 
;Pipe length in bytes 
;bytes written to pipe 


;Shared buffer size 
;Shared selector 
s;Shared buffer name 


;Clear screen 


;preserve selsctor 
;selector in extra segment 
;index equal 0 

;Create pipe 


stransfer read handle 
shandle in extra segment 


;Create system semaphore 


;Beep speaker 


@DosWrite write_hdl,msg_p0,lmsg_p0,bytes written 


errorl 
mov ax,bytes_ written 
mov es: [bp+4],ax 


=e 


@DosSemSet 
errorl1 


sem_hdll 


=e 


;transfer message length 
;length in buffer 


;Set semaphore 


Figure 3.22b (Continued) 


154 


Memory Management and Multitasking with Assembler Chap. 3 


;Create child process 


@DosExecPgm obj_name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 


errorl 
; 
@DosSenWait 


e 
a 


sem_hdll1,no_to 


@DosKillProcess 1,pid 


; 
ERROR11: 


@DosExit action, result 


; 
OS21 ENDP 


cls PROC NEAR 


@VioScrollUp 


ret 
ENDP 


ENDS 
END OS21 


;Wait for semaphore clear 


?Terminate child process 


;Exit 


;Clear screen 


tr,1lc,br,rc,no_line,blank,viohdl 


Figure 3.22b (Concluded) 


OPEN 
SEMAPHORE 


ADDRESS SHARED 
SEG. FOR PIPE HANDLE 
READ MESSAGE #1 
FROM PIPE 
WRITE TTY 
MESSAGE #1 
CLEAR 
SEMAPHORE 


Figure 3.23a Flowchart for a child 
process that illustrates pipes used for 
interprocess Communications. 
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TITLE PIPECL ~-- Check pipe generation (pipecl.asm) 


=e Me Me Me we 


-sall 

-xlist 
INCL_BASE equ 1 
include os2def.inc 
include bse.inc 

-list 


° 
’ 


errorli macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


agroup GROUP datal 

; 

STACK1 SEGMENT WORD STACK "STACK1' 
dw 1024 dup(?) 

STACK1 ENDS 


o 
DATA1 SEGMENT WORD PUBLIC 'DATA1' 


e 
’ 


result dw 0 

action equ 1 

viohdl equ 0 

; 

freq dw 5000 

duration aw 500 

; 

H > © © Oe Oe em ow me © 8 oe om Oe OO Oe > Om oe we om oe oe ee 
; Semaphore parameters 
? 

asenl db '\SEM\SDAT.DAT',0 
sem_hdl1 dada 

no to dd -1 

7 7 ae me > oe ee ee ee DP ee om > OD OO © OO OD 08 Om oe om on oe oe 
zero aw 0 

é 

7 oe eee ee em oe ee oe me OP ED DO ow Ow ee Om @® Oo om om ow 8 ae ow ow oe ee 
: Shared Buffer Parameters 
H > ae > © oe Om ee OD EP OD OO Om OF OD OD O® OF wD O@® Ob om ow oe oe oe 
shrsel dw ? 


shrname db 


e ™e@ Se te Re WO wWe 


read_hdl aw ¢ 
lmsg dw 2 
buffer db 


DESCRIPTION: This routine verifies that a pipe is 
generated. It uses semaphores for synchronization. 


;Stack for 2nd process 


;Exit code from process 
;Action code from process 
;Video handle 


75000 Hz 
7500 msec 


;Semaphore name 
;Address 
sNo time out 


;selector 
sbuffer name 


;read handle 
;length message 
;buffer length 


Figure 3.23b Routine for a child process, illustrating pipes for interprocess 
communications. 
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sactual bytes read 


ENDS 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACKl 
PROC FAR 


@DosOpenSem sem_hdli1,aseml ;Open system semaphore 
errorl 


@DosBeep freq, duration ;Beep speaker 
errorl 


@DosGetShrSeg shrname,shrsel ;shared segment 
errorl 

push shrsel ;preserve selector 
pop es s;load extra segment 
mov bp, zero sinitialize index 
mov ax,es: [bpt+2] ;read handle 

mov read_hdl,ax ;specified 

mov ax,es: (bp+4] ;message length 
mov lmsg,ax ;specified 


@DosRead read_hdl,buffer,1lmsg,bytes_read 
errorl 


@VioWrtTTY buffer, 1lmsg,viohdl ;Write message 
errorl 


@DosSemClear sem_hdli ;Clear semaphore 


ERROR11: 
@DosExit action, result ;Exit process 


0S21 ENDP 
CSEG ENDS 
END 


Figure 3.23b (Concluded) 


read handle and the message length for the pipe. The pipe is then read using 
@DosRead and the message loaded into buffer. The display is then updated with the 
message content using 


@VioWrtTTY buffer, l1msg, yiohdl 


where Imsg is the message length in bytes and viohdl the display handle. It is this 
access of the display that requires synchronization with the parent. 

Following the message write to the screen, the semaphore is cleared and 
the child process terminates execution. The key step in this code was to 
ensure that common pipe link exists between the routines. Unlike the sema- 
phore link, which uses a commonly named area (‘\SEM\SDAT.DAT’,0) across both 
the child and parent, the pipe handle was passed via a common memory area 
(‘\SHAREMEM\SDAT1.DAT’,0). 
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Figure 3.24a illustrates the main process for a set of programs that demonstrate 
queue operation. Figure 3.24b presents the associated code for this parent process. 
The process opens with a call to @DosCreateQueue. The common link between the 
child and parent is the queue name, ‘\QUEUES\QDAT.DAT’,0. This call returns a 
queue handle, q_hdl. The speaker is beeped and a child process (named 
‘QUEUECL.EXE’) turned on. The queue is used to pass a 32-bit buffer address 
from the child process to the parent. The selector value of this address is loaded into 
es and the offset into bx. This buffer address is contained in the double word 
buffer1. 


SETUP 
DATA 


CREATE 
QUEUE 


CREATE 
PROCESS 


PROCESS 


READ QUEUE 
BUFFER ADDRESS 


TRANSFER QUEUE 
BUFFER DATA TO 
PARENT BUFFER 


FREE QUEUE 
BUFFER AREA 


CLOSE 
QUEUE 


WRITE TTY 
MESSAGE 


KILL 
PROCESS 


Figure 3.24a Flowchart for a main 
program, illustrating queues for 
interprocess communications. 


EXIT 
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TITLE QUEUEST -- Check queue generation (queuest.asm) 


generated. 


=e ~e Te VO & 


-sall 


=e 


-xlist 
INCL_BASE equ 1 
include os2def.inc 
include bse.inc 
elist 


e 
a 


errorl macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


adgroup GROUP data 


STACK SEGMENT WORD STACK 'STACK' 
dw 1024 dup(?) 
STACK ENDS 


e 
DATA SEGMENT WORD PUBLIC 'DATA' 


e 
’ 


result dw 
action equ 


viohdl equ 
freq 
duration 
selector 


obj_name_buf 10 dup(?) 
lobj_name_buf $-obj_name_buf 
async 

argptr 

envptr 

pid 


| 
B 


“oe me we Me we VO WO ry 
Ry 


q hdl 
q_prty 


) 
q_name '\QUEUES\QDAT.DAT' , 0 


request 
el_prty 
asemi 

el_code 


DESCRIPTION: This routine verifies that a queue is 


;suppresses macro lists 


;suppresses source list 
;sets IBM macro flag 
7082 definitions 
;Dos,Vio,Mou, & Kbd 
;turns list on 


;exit macro 

;local macro label 

;set ax bits 

;jump if zero next instruction 
;otherwise exit process 


;end macro 
;data and extra group 


;Stack for main program 


;Exit code from main 
s;Action code from main 


:Video handle 


74000 Hz 
7500 msec 
;allocated segment selector 


;Process name buffer 
slength buffer 
sasynchronous operation 
;pointer arguments 
;environment pointer 
;process ID 

;process name 


;Queue handle 

;Queue ordering priority 
;name 

;Read request parameter 
;Element read priority 
;semaphore 

;element code 


Figure 3.24b Main program illustrating queues. 
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no_wait 


lmsg 


bufferl 


buffer 


56 dup(?) 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK 
PROC FAR 


@DosCreateQueue q_hdl,q prty,q name 
errorl 


@DosBeep freq, duration 
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swait processing 
;message length-~read 
;queue buffer address 
;read buffer 


;Create queue 


;Beep speaker 


;Create child process 


@DosExecPgm obj_name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 


errorl1 


;read queue buffer area 


@DosReadQueue q_hdl,request,1lmsg,bufferl,el_code,no_ wait,el_ prty,asemi 


errorl1 


mov bx,word ptr bufferl 
mov ax,word ptr buffer1+2 
mov selector,ax 

push selector 

pop es 

lea bp,buffer 

mov cx, lmsg 

mov di,O 


mov al,es: [bx+di] 
mov das: (bpt+dij],al 
inc di 

loop LOOP1 

@DosFreeSeg selector 
errorl 


@DosCloseQueue q hdl 


@vioWrtTTY buffer, lmsg,viohdl 
errorl 


@DosKillProcess 1,pid 


; 
ERROR11: 


e 
0S21 
CSEG 


@DosExit action,result 


ENDP 
ENDS 
END 


Figure 3.24b 


schild buffer 32-bit address 
selector 


;extra segment register 
;load data buffer address 
;count limit 

;count index 

;transfer from queue area 


;transfer to ds buffer 
sincrement index 


;free allocated segment 


;Close queue 


swrite message to screen 


;Terminate child process 


;Exit 


(Concluded) 


Next, the length of the buffer is loaded into a loop counter. This value, Imsg, 
was retrieved from the child process along with bufferl using an @DosReadQueue 
call. The contents of the buffer pointed to by bufferl are loaded into the buffer, and 
the segment area pointed at by selector, the segment address associated with the 
pointer, buffer1, is released. This segment was allocated previously, during execu- 
tion of the child process, as we shall see shortly. The queue is closed and the mes- 
sage in buffer written to the screen. Finally, the child is terminated and the parent 
exits back to OS/2. 
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Figure 3.25a shows the flowchart for the associated child process and Figure 
3.25b the corresponding code. The child opens with a beep to the speaker alerting 
the user that the child has started. Next, the queue is opened (note that the queue 
name represents the common link between the two processes. At this point the 
child allocates a segment using @DosAllocSeg. The size of the segment equals the 
message length and it is a giveable segment (aseg_give=1). The segment allocated 
has a selector returned (q_w) which is loaded into es and the contents of the mes- 
sage written to this buffer. The speaker is beeped with a slightly different tone, 
@DosGiveSeg executed (which returns a selector that can be given back to the 
parent, q_rr), and the 16-bit read selector loaded into the segment portion of a 32- 
bit pointer to the giveable segment (q_1r). | 

A macro @DosWriteQueuel has been defined at the beginning of the program 
and this macro has the fifth statement as pushing a 32-bit value (not address) onto 
the stack prior to the call to DOSWRITEQUEUE. This macro is called to transfer 


SETUP 
DATA 


BEEP #1 


OPEN 
QUEUE 


ALLOCATE QUEUE 
BUFFER AREA 


LOAD 
MESSAGE 


BEEP #2 


PERMIT ACCESS TO 
QUEUE BUFFER 


CLOSE 
QUEUE 


Figure 3.25a Flowchart for a child 
process, illustrating queues for 


EXIT pee 
interprocess communications. 
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TITLE QUEUECL -- Check queue generation (queuecl.asm) 


=e “te Ve Ve YO VE 


=e 


INCL_BASE equ 1 


include 
include 
-list 


macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


@DosWriteQueuel macro 
@define 
@pushw 
@pushw 
@pushw 
@pushd 
@pushw 
call 
endm 


agroup GROUP datal 


a 

STACK1 SEGMENT WORD 
dw 1024 dup(?) 

STACK1 ENDS 


os2def.inc 
bse. inc 


DESCRIPTION: This routine verifies that a queue is 
generated. It uses semaphores for synchronization. 


;suppress macro listing 


;suppress source list 
;set IBM macro flag 
;include os2 macros 
;Dos,Vio,Mou, & Kbd 
sturn list on 


sexit macro 

tlocal macro label 

;set ax 

;jump to next instruction 
rexit 


send macro 


;Corrected macro 


handle, request, length, data,prty 


DOSWRITEQUEUE 

handle 

request 

length 

data 

prty 

far ptr DOSWRITEQUEUE 


STACK ‘STACK1' 


DATA1 SEGMENT WORD PUBLIC 'DATA1' 


e 
‘ 


result dw 
action equ 
freq 

freql 
duration 


=e Se te te % 


\QUEUES\QDAT. DAT' , 0 


::define API call 
word handle 
word request 
buffer length 
32-bit address 
priority 
API function 


sload ds and es 


;Stack for 2nd process 


;Exit code from process 
;Action code from process 


35000 Hz 
72000 Hz 
7500 msec 


;queue handle 

sprocess ID--queue creator 
;name 

;write request parameter 
spriority message 1 


ee ame ame ete eee Os GD ca GED GD tee ne OD GED GED GED Om) Ge Ome oe ED OD Oe Oe we ew ee eS GD Oe Om owe ee os om OD On os on oe 


‘This is a priority 1 message',0ODH, OAH 


lmsg_p0O dw $~-msg_p0 


e 


slength 


Figure 3.25b The child process, illustrating queues for interprocess 


communications. 
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me Se te te 


qw ;queue write selector 

aseg_give sallocated segment giveable 
;queuve read 32-bit pointer 
;queue read selector 


ENDS 


CSEG SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK1 

0S21 PROC FAR 
@DosBeep freq,duration ;Beep speaker 
errorl 


@DosOpenQueue q_ pid,q hdl,q_name ;open queue 
errorl 


@DosAllocSeg lmsg_p0,q_w,aseg_give sallocate segment 
errorl 


sallocated segment selector 
spop to extra segment register 
;offset of message 
cx, 1lmsg_p0 sloop count=message length 
dai,o ;zero index 


al,ds: (bx+di] ;transfer message 
es:(di),al ;message to extra segment 
inc di ;increment index 
loop LOOP1 


push ds ;reload ds to stack 
pop es ;es=ds 


@DosBeep freqi, duration 72nd beep 
errorl 


@DosGiveSeg q.w,q pid,q rr ;get selector 
errorl 


lea bx,q r 732-bit read address 

mov ax,q_ rr 316-bit read selector 

mov ds: [bx+2],ax s;load read address 
;write address to queue 

@DosWriteQueuel q_hdl,request,lmsg_p0,q r,prty0 

errori 


@DosFreeSeg qw ;free allocated segment 
errorl 


@DosCloseQueue q_hdl ;close queue 
errorl 
; 
ERROR11: 
@DosExit action, result ;Exit process 
0S21 ENDP 
CSEG ENDS 
END 0S21 


Figure 3.25b (Concluded) 
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the 32-bit pointer to the allocated segment, back to the parent process via the queue. 
Also transferred with this call is the message length. Finally, the segment is set free 
for selector q_w. The queue is closed next and the child exits back to the OS/2. 


3.4.2 Shared Memory Segments 


In several cases among the preceding examples the processes involved employed 
shared memory segments. There were generally two types of mechanisms employed: 
giveable segments created using @DosAllocSeg or true shared segments created 
using @DosAllocShrSeg. Both of these approaches lead to a common sharing of a 
memory segment. These segments were used to transfer commonly needed informa- 
tion so that two independent (although possibly synchronized) processes could estab- 
lish a link. It is this need for some sort of common memory reference that charac- 
terizes all IPC, and shared memory is a very effective way to achieve this. 


3.5 SUMMARY 


In this chapter we have looked at memory management, multitasking, and inter- 
process communications. The goal has been to establish for the reader an introduc- 
tion to these techniques, with representative examples used to illustrate the mecha- 
nisms involved. A major attribute of OS/2 is the ability to access huge segments 
(greater than 64K). This was demonstrated in Section 3.2.4. 

Multitasking is a cornerstone of the operating system. As programming strate- 
gies change from the single-threaded way of doing business common throughout the 
1980s to more parallel approaches, OS/2 can be expected to move to the forefront 
of microcomputer operating systems. It must be recognized that multitasking requires 
a rethinking of how programs are structured in order to be able to take advantage of 
this feature. Programmers must begin to think in terms of how a given application 
can be subdivided so that the application can be run efficiently in a multitasked 
environment. This is a very nontrivial change in programming concept. Without the 
common availability of well-supported multitasking operating systems, it is, of 
course, impossible to begin the process of rethinking program structure to fit the 
multitasking mold. Hence OS/2 truly represents a transition in programming philoso- 
phy for the applications programmer. Fortunately, it has a great deal of commonal- 
ity with earlier systems such as DOS and the Windows executive, and consequently, 
represents a relatively fluid vehicle for many programmers to enter the world of 
multitasking. 

In Section 3.3 we discussed semaphores, multiple threads, and multiple proc- 
esses, all essential to a comprehensive multitasking environment. The semaphores 
treated consisted of two types: RAM and system (with a third being fast-RAM). In 
Section 3.4 we described the basic vehicles for interprocess communications, which 
had been alluded to earlier, and illustrated the use of pipes and queues. Shared 
memory segments were discussed throughout the chapter and signals were men- 
tioned briefly. 
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PROBLEMS 


3.1 IBM supplies a number of device drivers with the OS/2 libraries. They have extension 

| SYS. The floppy and fixed disk driver for the IBM PC/AT is called DISK01.SYS, 
and the driver for the inport Microsoft Mouse is MOUSEAO04.SYS, for example (see 
reference 5, p. 14). What level of protection would you expect these drivers to have? 
Why? 

3.2 Throughout this book the IBM (and Microsoft) macros have been used to access the 
API services. Typical of these is the call 


@DosExit action, result 


which executes the macro code 


@DosExit macro action, result 
@define DOSEXIT 
@pushw action 
@pushw result 
call far ptr DOSEXIT 
endm 


where @define and @pushw are defined as 


. @define macro callname 
ifndef callname 
extrn callname: far 
endif 
endm 


and 
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@pushw macro parm 
mov ax,parm 
push ax 
endm 


What are the advantages and disadvantages of this approach. Consider, for example, 
maintenance and clarity of code. 


3.3 When using @DosAllocSeg, what must occur for the segment to be created to be 
giveable? To be discardable? 


3.4 When accessing a huge segment, what is essential to achieving operation that ensures 
no violation of protection? 


3.5 What is the dominant feature of interprocess communications that must hold in any 
multitasking implementation? 


3.6 When would you be likely to use RAM semaphores for interprocess communications? 
To use system semaphores? 


3.7 In @DosWriteQueue why must the fourth macro parameter be pushed with @pushd 
not @pushs? Here 


@pushs macro parm 
mov ax,SEG parm 
push ax 
lea ax,parm 
push ax 
endm 


while 


@pushd macro parm 
push ds 
push bx 
mov ax, SEG parm 
mov bx,OFFSET parm 
push word ptr [bx] 
mov ax, [bx+2] 
push bp 
push sp 
pop bp 
xchg [bp+6],ax 
pop bp 
mov ds,ax 
pop ax 
pop bx 
push ax 
endm 


3.8 When a child process, that is, using semaphores for interprocess communications, 
completes the execution of a critical area of code, how does it signal the parent? 
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3.9 


3.10 
3.14: 
S12 
3.13 
3.14 
3.15 


3.16 
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Suppose that two processes involve no IPC and contain such code fragments as: 


Process 1 
@DosExecPgm... 
@errorl 


° 
Ud 


@DosBeep fregl,duration 


and 
Process 2 
Os21 PROC FAR 
; 
@DosBeep freq2,duration 
@DosExit action,result 
OS21 ENDP 


What are the potential consequences of such code? 

What is the major difference between a pipe and a queue as used in this chapter? 
Compare the various IPC mechanisms. 

When would you use a shared segment as opposed to a giveable segment? 
Outline the API calls for pipe operation using a child process. 

Outline the API calls for queue operation using a child process. 


How is an intraprocess thread differentiated from an interprocess thread? What is 
preferred for a second task? 


Discuss the usage of DosAllocSeg and DosReAllocSeg in comparison to the use of 
DosSubAlloc. 


PART Ill 
Advanced O$/2 Kernal Programming 


AI OS/2 and C 


There are a number of C compilers available; however, two that run under OS/2 
Protected Mode are the Microsoft C 5.1 Optimizing Compiler [1] and IBM’s C/2 
Version 1.1 [2]. In this book we use the former compiler. Together with the include 
files for the assembler (the .inc files), the IBM Toolkit [3] provides a set of C 
include files (.h files) that contain macros for accessing the Applications Program 
Interface (API) and Presentation Manager (PM) services. There are some significant 
difference’s between the Version 1.0 and 1.1 Toolkit files, particularly in the defi- 
nition of the structures used by API service calls. We will adhere to the Version 1.1 
definitions; the interested reader is referred elsewhere for the Version 1.0 definitions 
[4]. The purpose of this chapter is to introduce C programming in the Protected 
Mode context. 


4.1 HIGHER LEVELS OF ABSTRACTION 


C, by its very nature as a high-level language (HLL), is more abstract than assem- 
bler. This has distinct advantages when developing modular programs because the 
resulting code is more compact and easier to follow, assuming that the programmer 
has the language background. It does not necessarily facilitate optimum access to 
system hardware because the programmer must rely on the C compiler developer to 
provide these underlying service routines. In many cases, of course, these services 
are very optimized, but they must have some general-purpose features that could be 
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avoided if tailored assembler code were provided. This book assumes that the reader 
has a basic familiarity with the C language, as it did for assembler, and Appendix 
B reviews the C syntax in the Kernighan and Ritchie mold [5]. 

What do we mean by more abstract? Multiplication is an example. To square 
the variable x in C, one merely writes 


Ke oe. 


To square the same variable in assembler (assuming that x is of word length), one 
has 


mov ax, xX : load accumulator 

mov dx, 0 : clear upper multiplicand 
mul x ; multiply 

mov xX, ax s reload x variable 


which is a bit more cumbersome. An even more exaggerated example is the line of 
C code 


y = (float) (sin(2.*PI*£*t) ); 


The conversion from double precision to floating point, alone, is a major system 
call, as is the reference to the sine mathematical function. These calls would encom- 
pass many lines of assembler code to accomplish the same algorithm. 

Hence abstraction can be a desirable feature as the programmer moves away 
from low-level system services and the hardware. Assuming that a programmer’s 
span of attention is limited to some rough measure of lines of code, the HLL allows 
a more efficient usage of this feature. 


4.1.1 The C Include Files 


The Toolkit has a number of include files used to set up the API calls and associ- 
ated variables, types, and structures used by these calls. The Toolkit is highly rec- 
ommended for users who quickly wish to begin programming OS/2 Protected Mode 
C, with its function-like interface. The major Toolkit include file is 


OS2.h 
which calls 


#include <OS2def.h> 
#include <bse.h> 


and requires a beginning program statement 
#define INCL_BASE 


Hence the first line of code prior to any API call would be 
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#define INCL_BASE 
#include <0OS2.h> 


Note that OS2.h also has provisions to call pm.h, which loads the PM include 
routines. 
The file bse.h checks to see if INCL_BASE is set and then sets three symbols; 


INCL_DOS 
INCL _SUB 
INCL_DOSERRORS 


and (loads) 


#include <bsedos.h> /*Dos calls*/ 
#include <bsesub.h> /*Vio,Kbd,Mon calls*/ 
#include <bseerr.h> /*Error calls*/ 


where the first of these sets up the Dos prefix API calls. The second loads the Vio, 
Kbd, and Mon prefix API calls and bseerr.h loads the error calls. 

It is worthwhile pointing out a typical difference between the Version 1.0 
Toolkit and the Version 1.1. Consider the structure definition for getting the physi- 
cal buffer: 


Version 1.0 
struct PhysBufData { 
unsigned long buf_start; /*start byte*/ 
unsigned long buf_length; /*buffer length*/ 
unsigned selectors[2]; /*selector*/ 
}; 
Version 1.1 
typedef struct _VIOPHYSBUF{ 
PBYTE pBuf; /*pointer to start byte*/ 
ULONG cb; /*buffer length*/ 
SEL asel[1]; /*selector*/ 
}VIOPHYSBUF; 


Clearly, to access these two structures, which serve the same purpose, requires 
radically different calling schemes. The programmer can expect to encounter this 
type of problem when converting Version 1.0 Protected Mode code to Version 1.1; 
however, it is generally desirable to use the Toolkit routines because of the abstrac- 
tion features intrinsic to these calls. 


4.1.2 The Low-Level Nature of the API 


We know that standard C code can be used for output to the display with calls of 
the type: 


170 OS/2 and C Chap. 4 


printf("“This is a display message.\n”); 


This can be accomplished with the standard I/O include file stdio.h and works in 
Protected Mode as well as Real Mode. To use the API call in equivalent fashion, we 
would need the more structured statements 

unsigned vio_hdl = 0; /*video handle*/ 

char *msg _p = “This is a display message./n"; 

unsigned lmsg_p = 0; 


lmsg_p = strilen(msg_p); 
VioWrtTTy((char far*)msg_p,1lmsg_p,vio_hdl); 


Thus the reader can see that the API calls tend to be more cumbersome than stan- 
dard C code and more low level in nature. Clearly, as the example above high- 
lights, the programmer would want to use the standard I/O routines in this case. Fre- 
quently, however, services will be required in Protected Mode that cannot be accom- 
plished using the standard C functions. It is these activities that must access the API 
directly in low-level fashion. A very good example of this is the screen graphics 
modes, which require locking the screen and accessing the physical buffer all in 
conjunction with the mode set. These activities fit well with the notion of low-level 
calls in C. They correspond to low-level services: accessing the system resources 
directly. 

Generally, many of the API services are of this low-level nature. The reader is 
cautioned to use the standard C syntax where possible but recognize that the API 
services are designed to work in a multitasking environment and that some low-level 
interfacing will therefore always be necessary. 


4.1.3 Comparison of C with Assembler 


We have already seen several examples of the differences between C syntax and 
assembly language syntax when used to accomplish the same task. Typically, the 
assembler is much more detailed and incremental (each instruction accomplishes a 
much smaller piece of the overall task). As a further simplified example, consider 
addition in C: 


y = xl + x2; 
To accomplish this same syntax in assembler the following code is required: 


MOV ax, xX2 
add ax, xl 
MOV y, ax 


Again, this assumes word integer arithmetic. If floating-point operations, for ex- 
ample, are to be implemented, the overhead increases dramatically. 
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Why, then, have we spent time learning the assembler interface in OS/2? A 
major reason is to understand the low-level nature of the API interface. In order to 
program the API from any language, the programmer must have a feeling for the 
syntax at a very basic level. Frequently, access is byte oriented and in order to get 
C code to function properly, the programmer must have this very basic understand- 
ing. The structures and parameter definitions for C calls to the API rely on a low- 
level interpretation, as found in the assembler calls. When problems arise in the C 
debugging process, assembler-level understanding of the API services provides 
invaluable insight into the C function calls. 


4.2 INTRODUCTORY C PROGRAMMING WITH OS/2 


Many application programs require a reasonable level of mathematical sophistication 
to achieve their intended computational goals. Generally speaking, assembly lan- 
guage is not the desired vehicle to achieve such sophistication. Modern languages 
have evolved such that a great deal can be accomplished within a single language 
to span the requirement of sophistication yet retain the ability to implement low- 
level services. The C language is such an implementation, and from this point on we 
shall concentrate on programming for OS/2 in the C context. Of course, we will 
make an occasional sojourn back to assembly language when the need arises. 


4.2.1 C Program Architecture and Structure 


Perhaps the easiest way to present the structure of a C program is with a simple 
example. Figure 4.1 contains a C program that prints the message 


Input word integer less than 32,768 


reads the input word integer value, and calls a function times_2(). The function 
times_2( ) has a single formal parameter that it doubles and converts from integer 
to floating point. Then the function prints the floating-point value of twice the ini- 
tial integer to the display with the message 


2 times the integer value = 


with the equal sign followed by the value. 
What is typical about this code? First, a comment line has been offset with the 
following form: 


/* ees */ 


Next, the C files needed by the program have been specified. In this program there 
is only one, stdio.h, and it is included with the statement 


#include <stdio.h> 
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/* A simple C program to illustrate Protected Mode I/O -- ioprgm.c */ 
#include <stdio.h> 
main () 

int x; /* input variable */ 


printf("Input word integer less than 32,768 \n"); 
scanf ("%d", &x) ; 


times 2(x); /* function */ 


times_2(y) 
int y; /* formal parameter */ 


{ 
float z; /* floating point */ 


(float) (2.*y);? /* double */ 


printf("2 times the integer value = %f\n",z); 


Figure 4.1 The program ioprgm.c, illustrating typical program formatting for 
C code. 


Following this preprocessor area, the main function (called main()) appears and the 
code contained in this function is subtended within the curly brackets: {...}. The first 
line of code is a type declaration for x to be of type integer: int. Next the C stan- 
dard routine, printf(), is called, asking for the word integer input. The string con- 
tained in quotations is written to the display and terminated by the escape charac- 
ter, \n, which generates a carriage return and line feed. The scanf() routine is called 
to read an integer value (%d) into the location (using the address operator,&) speci- 
fied by x. Finally, the function times_2() is called with x passed as a parameter and 
main() is then ended. 

In the function times_2() the formal parameter, y, is declared to be of type 
integer and this is declared outside the body of the function. Within the body of the 
function all variables are locally defined. Here, for example, x is local to times_2() 
and is of type float (floating point). The value of y is doubled and converted to 
floating point with the cast: (float). This is used to define z. Next the value of z is 
output following the message. Note that the parameter specification (%f) corresponds 
to a floating-point output, while earlier we had (%d) to correspond to an integer 
format. 

Figure 4.2 illustrates the MAKE utility file used to compile and link the C 
code. In general the reader is referred to his or her compiler manual to understand 
the nature of this, but briefly the command 


cl -c -Zi -Os -FPc /Fcioprgm.cod ioprgm.c 


compiles the program (-c indicates do not link yet) and sets it up for the CodeView 
debugger (-Zi). The -Os parameter tends to reduce code size during optimization and 
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ioprgm.obj: ioprgm.c 
cl -c -Zi -Os -FPc /Fcioprgm.cod ioprgm.c 


ioprgm.exe: ioprgm.obj 
link /CO ioprgm.obj,ioprgm, ioprgm,slibce.lib/NOE os2.lib/NOE,, 


Figure 4.2.) MAKE file for ioprgm.c. 


-FPc generates floating-point calls and selects the emulator math package. The state- 
ment : 


/Fcioprgm.cod 


generates a mixed assembler and C code output file, and ioprgm.c indicates the C 
source file. 

The next set of lines in the MAKE file corresponds to the link operation. The 
/CO sets up CodeView. The first field contains the object modules(s); the second 
field contains ioprgm, where the default extension is .exe the run filename; and the 
third field contains ioprgm, the map filename with default .map. Next, the libraries 
are indicated, with the /NOE option that prevents multiple definitions of the same 
name. 

Figure 4.3 contains the list file for the mixed assembler and C source code 
(the .COD file). It is important to examine this file because it establishes the com- 
plexity of the C code in relation to the required assembly language instructions 
needed to represent each line of this C code. Note the large number of external 
routines called to implement the program appearing in Figure 4.1: __acrtused, 
_printf, scanf, chkstk, fldw, fmnld,_fstsp,__flds, _fstdp, and __fltused. 
The text segment is TEXT and the data segment DAT. The data segment contains 
the strings of text and the integer formal specifier, %d. Aside from the initial setup 
for the routine _main, the print output asking for the integer less than 32,768 is 
accomplished with the assembly code following the designation for line 9. Next the 
integer is read in and a call made to times_2(). Finally, the main procedure ends. 
The times_2() code follows as a NEAR procedure with a number of calls to float- 
ing-point routines that emulate the coprocessor. These routines all begin with “f ”. 

The code in Figure 4.3 is instructive in that it illustrates the general techniques 
for generating assembly language instructions from C syntax. Note that no obvious 
Protected Mode calls were evident. These are all buried in the routines _ printf and 
_scanf. The basic C compiler template, however, is evident using TEXT, DATA, 
and DGROUP. 


4.2.2 Accessing the API from C 


The API is accessed in much the same fashion from C as it is from assembly lan- 
guage. Using the Toolkit definitions it is possible to set up the C function calls in 
a comfortable style for usage. Consider, for example, the prototyping for DosExit: 
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_TEXT 
_TEXT 
_DATA 
_DATA 
CONST 
CONST 
_BSS 

_BSS 


$$SYMBOLS 


Static Name Aliases 


TITLE ioprgm.c 
NAME Lloprgm 


. 8087 

SEGMENT WORD PUBLIC ’ CODE’ 
ENDS 

SEGMENT WORD PUBLIC ’ DATA’ 
ENDS 

SEGMENT WORD PUBLIC ’ CONST’ 
ENDS 

SEGMENT WORD PUBLIC ’BSS’ 
ENDS 

SEGMENT BYTE PUBLIC 


$$SYMBOLS ENDS 
S$TYPES SEGMENT BYTE PUBLIC ’DEBTYP’ 
S$TYPES ENDS 


DGROUP 


EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 


EXTRN - 


EXTRN 
EXTRN 
EXTRN 
_DATA 


$SG159 
$SG160 
$S5G165 


_DATA 
_TEXT 


3 KK 
> bOkKK 
5 | KKK 
» DORK 
3 | eK 
3 tok 


GROUP CONST, _BSS, _DATA 
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ASSUME CS: _TEXT, DS: DGROUP, SS: DGROUP 


__acrtused: ABS 
_printf: NEAR 
_scanf:NEAR 
__chkstk: NEAR 
__fldw: NEAR 
__fmuld: NEAR 
__fstsp:NEAR 
__filds:NEAR 
__fstdp: NEAR 
__fltused: NEAR 
SEGMENT 


DB ’Input word integer less than 32,768 ’, 


DB *%a’, OOH 


DB 72 times the integer value = %f’, OaH, 


ENDS 
SEGMENT 
ASSUME CS: _TEXT 


/* A simple C program to illustrate Protected Mode I/0 -- ioprgm.c */ 


#Hinclude <stdio.h> 


main( ) 


; Line 6 


_main 


> OKK 


PUBLIC _main 
PROC NEAR 

xkk 000000 
*Kkx OGOOOL 
xkxk 000003 
*xkk OOO006 

x = -2 

int x; 


push bp 

mov bp,sp 
mov ax,2 
call __chkstk 


/* input variable */ 


printf("Input word integer less than 32,768 \n"); 


*kk 000009 b8 00 00 
KKK O0000c 50 

xxx 00000d e8 00 00 
*xk*k 000010 83 c4 02 
scanf ("%d" ,&x); 


; Line 10 


7x 


kkk 000013 8d 46 fe 


xxx 000016 
*xKk 000017 26 00 


mov ax,OFFSET DGROUP: $$G159 
push ax 

call _printf 

add sp,2 


lea _ax,WORD PTR [bp-2] 


push ax 
mov ax,OFFSET DGROUP: $SG160 


Figure 4.3 The >COD file for ioprgm.c. 
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*KK 00001a push ax 
*kKK OO001b call _scanf 
*x*k O0001e add sp,4 

+ OK 

3 | KKK times _2(x); /* function */ 

; Line 12 
*x*kx 000021 push WORD PTR [bp-2] ;x 
*xkKx 000024 call _times_2 
*xk*k 000027 add sp,2 

3 KKK } 

; Line 13 
*xkKx O000Za sp,bp 
xKK QO0002c bp 
*xKx O0002d 


_main ENDP 
3 OKK 
3) **K times _2(y) 
3 (ROKK int y; /* formal parameter */ 
; Line 16 
_TEXT ENDS 
CONST SEGMENT 
$T20002 DQ 04000000000000000r ; 2.000000000000000 
CONST ENDS 
_ TEXT SEGMENT 
ASSUME CS: _TEXT 
PUBLIC _times_2 
_times_2 PROC NEAR 
xxkk 00002e 55 
xKK OOOO2ZFT 8b 
*kKx 000031 b8 , 
*xkKK 000034 e8 __chkstk 
*k*k 000037 56 si 
5 KK { 
Line 17 
4 
z= -4 
float 2; /* floating point */ 


(float) (2. xy); /* double */ 


Line 20 
xkK 000038 8d lea bx,WORD PTR [bp+4] 


*xkx 0Q0003b e8 call __fidw 

xkxK OJ0003e 8d lea bx,WORD PTR $T20002 
kKx 000042 e8 call __fmuld 

*xkkK 000045 8d lea bx,WORD PTR [bp-4] 


xkxk 9000048 e8 call __fstsp 
> | KKK 
3 | OK printf("2 times the integer value = %*f\n",z); 
; Line 22 
xKk QO0004b 5e fc lea bx,WORD PTR [bp-4] 
re 
*kk 00004e 00 00 call __fids 
*x*Kk QOOOOS51 ec 08 sub sp,8 
*xkKK 000054 dc mov bx, sp 
KKK QO00056 00 00 call __fstd 


Pp 
*xk 000059 29 00 MOV ax,OFFSET DGROUP: $5G165 


*xkK GOOO05c push 
*kKK 00005d 00 00 call 
*xkk 000060 c4 0a add 
3}; Line 23 © 

x46k 000063 pop 
xkk 000064 e5 mov 
*kk JNO0066 pop 


Figure 4.3. (Continued) 
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*xKK QOOGO67 


_times_2 ENDP 


_TEXT ENDS 
END 


Figure 4.3. (Concluded) 
VOID APIENTRY DosExit(USHORT, USHORT) 
Here the Toolkit definitions are 


#define VOID void 
#define APIENTRY pascal far 
Typedef unsigned int USHORT; 


The definitions have their usual meaning in C, and the only one needing an expla- 
nation is the type pascal. Pascal refers to the calling convention used in accessing 
the function DosExit. When a C function is called the formal parameters are loaded 
on the stack, starting with the last parameter first. In the pascal convention the last 
parameter is loaded last. In the assembler instruction set, the PUSH instruction puts 
its operand on the stack and decrements the stack pointer. Hence, the initiating 
assembly language code sequence (at the beginning of each function) 


push bp 
mov bp,sp 
sub sp,N 


causes the previous module’s (or calling module’s) base pointer, bp, to be saved on 
the stack and the current stack pointer value, sp, placed in bp. Prior to execution of 
this code, the calling program caused the called function (procedure) parameters to 
be placed on the stack along with a return address (invoked at the CALL) for the C 
convention. The called program places the parameters on the stack along with a 
return address for the pascal convention. The “sub sp,N” instruction above simply 
reserves N bytes of stack for local usage (N should be even). 

The API definitions include a large class of type definitions, such as PCHAR, 
for a pointer to a character where 


typedef CHAR FAR *PCHAR; 
Similarly, 
typedef ULONG FAR *PULONG 


defines a pointer to a LONG variable. 
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A particularly important definition, is one that allows the programmer to estab- 
lish a FAR pointer: 


#define MAKEP(sel,off) ((PVOID)MAKEULONG(off,sel) ) 


where 
typedef VOID FAR *PVOID; 


and 


#define MAKEULONG(1,h) ((ULONG)(((USHORT)(1)) | 
( (ULONG ) ( (USHORT) ) (h) ) )<<16) ) 


Access of the video context, for example, is via the following sequence: 


VioSetMode (((struct_VIOMODEINFO far*)&CGAm),vio_hdl); 
VioScrLock (wait2, (char far *)dstatl,vio_hdl); 


VioScrUnLock(vio_hdl) ; 


Here the structure VIOMODEINFO is defined as CGAm and must satisfy the API 
constraints for structure members. It is defined in the Toolkit context as 


typedef struct _VIOMODEINFO { 

USHORT cb; 
UCHAR fbType; 
UCHAR color; 
USHORT col; 
USHORT row; 
USHORT hres; 
USHORT vres; 
UCHAR fmt_ID; 
UCHAR attrib; 
} VIOMODEINFO; 


Note that the structure above has the same form as the structure used in the assem- 
bly language programs except for the two added parameters, which are reserved and 
of no significance to the current programs. The video handle is short and declared 


with 
SHANDLE vio_hdl = 0; 
where 


typedef unsigned short SHANDLE; 
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The remaining parameters are defined as would be expected in the usual C conven- 
tion. 

This, then, is how the API access is achieved based on the Toolkit definitions. 
The programmer can, of course, choose to develop his or her own definitions; 
however, it can be expected that they would be similar to those found in the 
Toolkit. Note that the function prototyping follows the assembler conventions estab- 
lished in the API library by IBM. The parameter setup in these calls is similar to 
that established for the basic assembler routines except that a pascal convention has 
been used. 


4.2.3 Graphics Using C and OS/2 


Figure 4.4 illustrates the MAKE file for a program swave.c, which plots a dynami- 
cally varying sine wave. Figure 4.5a is the flowchart for swave.c and Figure 4.5b 
the actual program code for this module. This code opens with the needed include 
file accesses and then sets up the keyboard buffer, an associated structure, several 
integer and character parameters, and the floating point arrays x[] and y[]. Next the 
principal calling routine, the function main(Q, is established. 


swave.obj: 
cl -c -Zi -Os -FPc swave.c 


gphrout.obj: gphrout.c 
cl -c -Zi -Os -FPc gphrout.c 


swave.exe: swave.obj gphrout.obj 
link /CO swave.obj+gphrout.obj,swave,,slibce.lib/NOE os2.1lib/NOE 


Figure 4.4 MAKE file for swave.c. 


In the beginning of main(), a number of structures are defined: the physical 
buffer (PVBPrt2) and two video mode structures (CGAm and STDm). These all 
follow the convention of the Toolkit and the OS/2 parameter definitions for the API 
calls [6]. The sine wave is to be iteratively displayed: Each iteration is incremented 
a finite time interval to simulate motion. The total number of iterations read is 
followed by the setup for the video CGA mode. The first VioSetMode parameter 
could have been specified as 


(PVIOMODEINFO) &CGAm 


instead of using the structure-oriented syntax. The screen is locked and the physical 
buffer accessed, using VioGetPhysBuf(). Note that this access allows the program to 
return a selector to the buffer, PVBPrt2.asel[0]. The call to sine_wave() includes 
specification of the number of iterations and the selector to the physical buffer. Once 
the return from sine_wave() takes place, the screen is unlocked and a keyboard 
hesitate implemented. This is followed by a reset of the mode to 80 x 25 (STDm) 
and the program exit. 
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Figure 4.5a Flowchart for swave.c. 


The sine_wave() program generates an array of 199 points of the sine wave of 
frequency 1 Hz and time interval of 0.02 second. This figure is plotted on the dis- 
play and then removed [with upltptQ]. After each plot followed by removal, the time 
value is incremented by one-tenth of a second. The routine cclsCGAQ clears the 
CGA screen. Note that it functions similarly to the earlier main() calls to lock, 
unlock, and get the screen buffer. This routine calls clrCGAQ, which actually writes 
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/* This routine sets & clears CGA mode with screen clear--swave.c 
* The generalized nomenclature is used. 

* A dynamic sine wave has been added to the CGA mode output. 

* This sine wave gradually moves across the screen 

* The routine calls gphrout.c graphics functions. */ 


#define INCL_BASE /* Conditional load */ 
#include <os2.h> 
#include <math.h> 


struct _STRINGINBUF lkbd_buf; keyboard buf len */ 
CHAR kbd_buf[80]; /* keyboard buffer */ 


UINT action = 0; /* end thread */ 
UINT error_code = 0; /* result code */ 
UINT wait = 1; /* reserved word */ 


CHAR dstat(1]; /* lock status */ 
CHAR dstat1[1]; /* lock status */ 


float x[{250),y[250); 


screen coords */ 


main() 


( 


SHANDLE vio_hdl = 0; /* video handle */ 
SHANDLE kbd_hdl = 0; /* keyboard handle */ 
UINT wait2 = 1; /* reserved */ 

UINT xb = 75,xe = 150,yb = 25,ye = 175; /* box points */ 

SEL MM1; /* selector */ 


int no_iter; number iteration */ 


struct _VIOPHYSBUF PVBPrt2; /* physical buffer */ 
struct _VIOMODEINFO CGAm; /* CGA structure */ 
struct _VIOMODEINFO STDm; /* 80 x 25 struct */ 


PVBPrt2.pBuf = (BYTE far *) (OxB8000) ; buffer start */ 
PVBPrt2.cb = 0x4000; /* buffer size */ 


CGAm.cb = 12; . /* struct length */ 
CGAm.fbType = 7; /* CGA mode */ 
CGAm.color = 2; /* CGA color */ 
CGAm.col = 40; /* text columns */ 
CGAm.row = 25; /* text rows */ 
CGAm.hres = 320; /* CGA hor res */ 
CGAm.vres = 200; 7/* CGA vert res */ 


STDm.cb = 12; /* struct length */ 
STDm.fbType = 1; /* 80 X 25 mode */ 
STDm.color = 4; /* STD color */ 
STDm.col = 80; /* text columns */ 
STDm.row = 25; /* text rows */ 
STDm.hres = 720; /* STD hor res */ 
STDm.vres = 400; /* STD vert res */ 
lkbd_buf.cb = 80; /* buffer size */ 


printf("Input number of iterations\n") ; 


scanf ("%d",&no_iter) ; no. updates */ 


set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl); 


cclsCGA(vio_hdl) ; /* clear CGA screen */ 


VioScrLock(wait2, (char far *)dstat1,vio_hdl);. /* lock screen */ 
/* physical buffer */ 


Figure 4.5b The program swave.c, which plots a dynamic sine wave. 
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VioGetPhysBuf ((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl); 
MM1 = PVBPrt2.asel[(0]; /* selector */ 
sine_wave(no_iter,MM1) ; /* sine wave */ 


VioScrUnLock(vio_hdl) ; /* unlock screen */ 
/* hesitate screen */ 
KbdStringIn((char far *)kbd_buf, 
((struct _STRINGINBUF far *)&lkbd_buf), 
wait,kbd_hdl); 
/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &STDm) ,vio_hdl) ; 


DosExit (action, error_code) ; 


} 


sine_wave (NN, MM1) 
int NN; 
SEL MM1; 


{ 

float scale=35.,mid=100. ; plot parameters */ 
int mmid=100, zero=0, end=200,npts=199,n1,n; 

double PI = 3.141592654,t; 


t = 0.0; start time */ 


for(nl=1;n1 <= NN;n1++) loop screens */ 

{ 

for(n=1;n <= npts;n++) loop array pts */ 
{ 
y{n]=scale* (float) (sin(2.*PI#*t) ); sine wave */ 
y(njJ=mid-y{n]; adjust plot */ 
x(n}=(int) (n); col coordinate */ 
t =t +.02; increment time */ 


) 


for(n=l1;n <= (npts-1) ;n++) 
pltpt(x[{n],x{n+1),y[n],y[{n+1] ,MM1) ; plot points */ 


for(n=1;n <= (npts-1) ;n++) 
upltpt(x[(n],x{n+1),y[n}],y({n+1] ,MM1) ; unplot points */ 


t=t+0.1; major shift */ 
) 
) 


cclsCGA(vio_hdl1) 
SHANDLE vio_hdli; 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 


PVBPrt1.pBuf = (BYTE far *) (0xB8000) ; /* phys buf start */ 
PVBPrtl.cb = 0x4000; /* buffer length */ 


VioScrLock(waiti1, (char far *)dstat,vio_hdl1l); /* lock screen */ 

/* physical buffer */ 
VioGetPhysBuf ((struct _VIOPHYSBUF far *)&PVBPrt1,vio_hdl1l) ; 
MM = PVBPrtl1.asel[(0]j; /* selector */ 


C1rCGA (MM) ; /* CGA clear */ 


Figure 4.5b (Continued) 
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VioScrUnLock(vio_hd11) ; unlock screen */ 


C1rCGA (MM) 
SEL MM; 

{ 

INT n; 

INT N1 = Ox1F3F; end odd buffer */ 

INT DM = 0x2000; even offset */ 

PCHAR ptr; pointer scr buf */ 


for(n = O;n <= Ni1;ntt) 


{ 
ptr = MAKEP(MM,n) ; odd far pointer */ 
*ptr = 0; clear odd buffer */ 


} 
for(n = O;n <= N1;nt+) 


ptr = MAKEP(MM, DM+n) ; even far pointer */ 
*ptr = 0; clear even buffer */ 
} 

} 


Figure 4.5b (Concluded) 


a zero to each byte in the CGA buffer area. The function MAKEP( is used to 
generate the pointer to the physical buffer values, with the selector value passed 
from the earlier VioGetPhysBuf() call and the offset generated internally. 

Figure 4.6 illustrates the graphics routines used in the calls to generate the sine 
wave graphics: wdot(, uwdot(), pltptQ, and upltptd. In addition, a box drawing 
routine bboxx() and the vertical and horizontal line drawing routines are included. 


4.2.4 Low-Level Access for Printer Graphics 


Figure 4.7 illustrates the MAKE file for a program, prtwave.c, which plots a sine 
wave on the graphics printer (in this case an Epson FX-85 dot matrix printer). The 
MAKE file specifies three C source code files: prtwave.c, the actual sine wave 
generator; pprtscr.c, a C source code file that contains the code to drive the printer; 
and gphrout.c, the graphics routines specified in Figure 4.6. 

Figure 4.8a illustrates the flowchart for prtwave.c and Figure 4.8b the corre- 
sponding source code for prtwave.c. This code is very similar to the program 
swave.c except that the printer routine arrays have been declared in the preproces- 
sor area and a new sine wave routine, ssine_wave(), is called. This routine plots a 
single sine wave of 199 points at a selected frequency read in from main(). A call 
to prtscr() causes the screen to print on the printer. 

Figure 4.9a illustrates the flowchart for the print-screen CGA mode routine, 
pprtscr.c. Figure 4.9b contains the code for this routine. Note that this routine per- 
forms exactly like its counterpart, prtscr.asm, in assembly language. The only differ- 
ence is that an intermediate 16,000-byte buffer is not used. The same ESC charac- 
ter outputs are sent to the printer via DosWrite() once the printer is opened as a file 
device using DosOpen(). The data from the CGA screen is output as 25 blocks of 
640 bytes (eight rows by 80 bytes per row). The routine Idarray is used to load 
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/* Graph routines Protected Mode--gphrout.c */ 


#define INCL_BASE 
#include <os2.h> 


bboxx (xb, xe, yb, ye, MM1) 
UINT xb,xe,yb,ye; 
SEL MM1; 
{ 
lineh (yb, xb, xe,MM1) ; 
lineh(ye,xb,xe,MM1) ; 
linev (xb, yb, ye,MM1) ; 
linev (xe, yb, ye,MM1) ; 


} 
lineh(y,x1,x2,MM1) 
UINT y,x1,x2; 
SEL MM1; 
{ 
UINT n; 
for(n = xl;n <= x2;n++) 
wdot(n,y,MM1) ; 


} 
linev(x,y1,y2,MM1) 
UINT x,yl,y2; 
SEL MM1; 
{ 
UINT n; 
for(n = yljn <= y2;n++) 
wdot (x,n,MM1) ; 


) 
wdot (x, y,MM1) 

UINT x,y; 

SEL MM1; 


{ 

PCHAR ptr; 

UINT DM = 0x0000; 
CHAR MASK1 = 0x01; 


if(y & 0x01) 
DM = 0x2000; 


ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 2))); 
*ptr =(*ptr | (MASK1 << (2*(3 - x % 4)))); 


uwdot (x, y,MM1) 
UINT x,y; 
SEL MM1; 


{ 

PCHAR ptr; 

UINT DM = 0x0000; 
CHAR MASK1 = 0x00; 


if(y & 0x01) 

DM = 0x2000; 
ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 
*ptr = (MASK1 << (2*(3 - x % 4)))? 


} 
pltpt(x1,x2,y1,y2,MM1) 

float x1,x2,yl1,y2; 
SEL MM1; 

{ 

float m; 

int row; 

int col; 


if(xl == x2) 
1000.; 


top line */ 
bottom line */ 
right line */ 
left line */ 


hor line */ 


vertical line */ 


x=col,y=row */ 


set dot */ 


even buffer */ 
dot location */ 
"OR" dot */ 


clear dot */ 


even buffer */ 
dot location */ 
write undot */ 


slope */ 


zero divide */ 


Figure 4.6 Graph routines used in the library cgraph.lib and taken from 


gphrout.c. 
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else 
m= (y2-y1)/(x2-x1); /* normal slope */ 
if( x2 > x1) 
{ 
for(col = (int) (x1)+1l;col <= (int) (x2) :col++) 
{ 
row =(int) (yl + m*(col - x1)); /* line equation */ 
wdot (col, row, MM1) ; /* write dot */ 
} 
else 
{ 
if(x2 < x1) 
for(col =(int) (x2)+1;col <= (int) (x1) ;col++) 


row=(int) (y2 + m*(col - x2)); 


wdot (col, row, MM1) ; /* write dot */ 
} 
else 
col = (int) (x1); /* verticle line */ 
if(yl > y2) 
{ 
for (row=(int) (y2)+l;row <= (int) (yl) ;row++) 
wdot (col, row, MM1) ; 
) 
else 
{ 
for (row=(int) (y1)+l;row <= (int) (y2) ;rowt++) 
wdot (col, row, MM1) ; 
) 
} 


} 


upltpt (x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2:? 


SEL MM1; 
{ 
float m; /* slope */ 
int row; 
int col; 
if(xl == x2) /* zero divide */ 
m = 1000.;3 
else 
m= (y2-y1)/ (x2-x1) ; /* normal slope */ 
if(x2 > x1) 
{ 
for(col = (int) (x1) 7col <= (int) (x2) ;col++) 
{ 
row = (int) (yl + m*(col - x1)); /* line segment */ 
uwdot (col, row, MM1) ; /* erase dot */ 


) 


) 
else 


{ 
if(x2 < x1) 
{ 
for(col = (int) (x2)+1l;col <= (int) (x1) ;col++) 
row=(int) (y2 + m*(col -x2)); 
uwdot (col, row,MM1) ; /* erase dot */ 
} 
} 


else 


{ 
col = (int) (x1); 


if(yl > y2) 
for (row=(int) (y2)+l;row <= (int) (yl) ;row++) 
uwdot (col, row, MM1) ; /* erase dot */ 
} 
else 


{ 
for (row=(int) (y1)+l;row <= (int) (y2) ;row++) 

uwdot (col, row, MM1) ; /*® erase dot */ 
} 
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obj: prtwave.c 
cl -c -Zi -Os -FPc prtwave.c 


obj: pprtscr.c 
cl -c -Zi -Os -FPc pprtscr.c 


obj: gphrout.c 
cl -c -Zi -Os -FPc gphrout.c 


exe: prtwave.obj pprtscr.obj gphrout.obj 
link /CO prtwave.obj+pprtscr.obj+gphrout.obj,prtwave,,\ 
Slibce.lib/NOE os2.lib/NOE, 


Figure 4.7. MAKE file for prtwave.c, which plots a sine wave on the printer. 


Figure 4.8a Flowchart for a program 
prtwave.c, which plots a sine wave on 
the printer. 
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/* This routine sets & clears CGA mode with screen clear--prtwave.c 
* The generalized nomenclature is used. 

A sine wave has been added to the CGA mode output. 

The routine calls gphrout.c graphics functions. 

It prints the plot. */ 


#define INCL_BASE Conditional load */ 
#include <os2.h> 
#include <math.h> 


struct _STRINGINBUF lkbd_buf; keyboard buf len */ 
CHAR kbd_buf[80]; keyboard buffer */ 


UINT action = 0; end thread */ 
UINT error_code = 0; result code */ 
UINT wait = 1; reserved word */ 


CHAR dstat[1]; lock status */ 
CHAR dstatl1[1]; lock status */ 


float x[{250)],y[250]; screen coords */ 
BYTE col1[320]; column array */ 
BYTE MM[4] = {0x40,0x10,0x04,0x01}; mask */ 

BYTE w[8] = {128,64,32,16,8,4,2,1}; weights */ 

BYTE s[4]; dummy */ 

BYTE shift1[(4] = {6,4,2,0)}; shift count */ 
BYTE in_buffer1[4] {0x1B,0x4B,64,1}; ESC K (320-256) */ 
BYTE in_buffer2[2] {0x0OD, Ox0OA}; CR,LF */ 

BYTE in_buffer3[(3] {0x1B,0x41,8); ESC A 8/72 */ 
BYTE in_buffer4[(2] {0x1B,0x32}; ESC 2 */ 

BYTE dev_name[5]} = {'L','P','T','1',0}3 device */ 


main() 
extern prtscr(); PrtSc routine */ 


SHANDLE vio_hdl : video handle */ 
SHANDLE kbd_hdl keyboard handle */ 
UINT wait2 = 1; reserved */ 

UINT xb = 75,xe 150,yb = 25,ye = 175; box points */ 

SEL MM1; selector */ 


float freq; frequency */ 


struct _VIOPHYSBUF PVBPrt2; physical buffer */ 
struct _VIOMODEINFO CGAm; CGA structure */ 
struct _VIOMODEINFO STDm; 80 x 25 struct */ 


PVBPrt2.pBuf = (BYTE far *) (0xB8000); buffer start */ 
PVBPrt2.cb = 0x4000; buffer size */ 


CGAm.cb = 12; struct length */ 
CGAm.fbType = 7; CGA mode */ 
CGAm.color = 2; CGA color */ 
CGAm.col = 40; text columns */ 
CGAm. row = 25; text rows */ 
CGAm.hres = 320; CGA hor res */ 
CGAm.vres = 200; CGA vert res */ 


STDm.cb = 12; struct length */ 
STDm.fbType = 1; 80 x 25 mode */ 
STDm.color = 4; STD color */ 
STDm.col = 80; text columns */ 
STDm.row = 25; text rows */ 
STDm. hres 720; STD hor res */ 
STDm.vres 400; STD vert res */ 


Figure 4.8b The program prtwave.c. 
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lkbd_buf.cb = 80; /* buffer size */ 


printf("Input frequency (Hz) \n"); 
scanf ("%f", &freq) ; 


/* set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl) ; 


cclsCGA(vio_hdl) ; /* clear CGA screen */ 
VioScrLock(wait2, (char far *)dstat1,vio_hdl); /* lock screen */ 


/* physical buffer */ 
VioGetPhysBuf ((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl) ; 


MM1 = PVBPrt2.asel[(0]; /* selector */ 
ssine_wave(freq,MM1) ; /* sine wave */ 
prtscr (MM1) ; /* print screen */ 
VioScrUnLock (vio_hdl) ; 7* unlock screen */ 


/* hesitate screen */ 
KbdStringIn((char far *)kbd_buf, 
((struct _STRINGINBUF far *) &lkbd_buf), 
wait,kbd_hdl); 
/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &STDm) , vio_hdl) ; 


DosExit (action,error_code) ; 


} 


ssine_wave (freq, MM1) 
float freq; 
SEL MM1; 
{ 
float scale=35.,mid=100.; /* pilot parameters */ 
int mmid=100, zero=0, end=200,npts=199,n1,n; 
Gouble PI = 3.141592654,t; 


t = 0.0; /* start time */ 
for(n=l1;n <= npts;n++) /* loop array pts */ 
{ 
y(n])=scale* (float) (sin(2.*PI*freq*t) ) ; /* sine wave */ 
y(n]=mid-y[(n]; /* adjust plot */ 
x{n]=(int) (n); /* col coordinate */ 
t= t +.02; /* increment time */ 


} 
for(n=l;n <= (npts-1) ;n++) 
pltpt(x[{n},x[{n+1],y[n],y{n+1],MM1) ; /* plot points */ 


} 


cclsCGA(vio_hdl1) 
SHANDLE vio_hdli; 
{ 


SEL MM2; Bi 

UINT waitl = 1; 

struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 
PVBPrt1.pBuf = (BYTE far *) (0xB8000) ; /* phys buf start */ 
PVBPrtl1.cb = 0x4000; /* buffer length */ 


VioScrLock(waitl1, (char far *)dstat,vio_hdll); /* lock screen */ 
/* physical buffer */ 
VioGetPhysBuf( (struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll); 


MM2 = PVBPrtl.asel[0]; /* selector */ 


Figure 4.8b (Continued) 
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Cl1rCGA (MM2) ; CGA clear */ 


VioScrUnLock(vio_hdl1) ; unlock screen */ 


cl1rCGA (MM3) 
SEL MM3; 
{ 
INT n; 
INT N1 = Ox1F3F; end odd buffer */ 
INT DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= Ni;n++) 


{ 
ptr = MAKEP(MM3,n) ; odd far pointer */ 
*ptr = 0; Clear odd buffer */ 


for(n = O;n <= Ni;n++) 


{ 
ptr = MAKEP(MM3,DM+n) ; even far pointer */ 
*ptr = 0; clear even buffer */ 


} 


} 


Figure 4.8b (Concluded) 


these eight rows in the following manner: For each of the 80 bytes in a row, the 
byte is unfolded into its four pixel values (to make the 320 pixels per CGA row). 
The single byte containing the four pixel values is stored in four locations: s[0], s[1], 
s[2], and s[3]. These values are in turn masked, shifted, and weighted according to 
their row position. A running total is generated across all rows for each pixel posi- 
tion and stored in col1[]. The coll[{] values are returned to prtscr() (the pprtscr.c 
function that accomplishes the screen print). Each buffer row and column value is 
returned using 


prt = MAKEP (MM1, DM + (80 *(row>>1) + (col>>2))); 


Here MM1 is the selector value and DM = 0x2000 if the row value is odd. Figure 
4.10 illustrates a typical sine wave plotted using this program. 


4.3 MEMORY MANAGEMENT AND MULTITASKING WITH C 


The API services offer a wide variety of multitasking and memory management 
options, as we have seen. There is an important constraint to consider when employ- 
ing programs that run in a multitasking environment: The code is reentrant if differ- 
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/* This is a C print screen routine -- pprtscr.c */ 


#define INCL_BASE 
#include <os2.h> 


prtscr (MM1) 
SEL MM1; /* selector */ 


extern BYTE in_bufferi[]; /* ESC K (320-256) r */ 

extern BYTE in_buffer2[]; /* CR,LF */ 

extern BYTE in_buffer3[]; /* ESC A 8/72 */ 

extern BYTE in_buffer4[]; /* ESC 32 -- 1/6 */ 
/* byte counts */ 

USHORT bytesin=320,bytesout=0,bytesinl=4,bytesin2=2,bytesin3=3; 


extern BYTE dev_name[]; /* device name */ 


HFILE dev_hand = 0; /* handle */ 

USHORT dev_act = 0; /* action */ 

ULONG dev_size = 0; /* size */ 

USHORT dev_attr = 0; /* attribute */ 
USHORT dev_flag = 1; /* open file */ 
USHORT dev_mode = 0x00C1; /* private,nodeny */ 
ULONG dev_rsv = 0; /* reserved */ 


extern BYTE coll[]j; 7* column array */ 


UINT N; /* block count */ 
int blk_cnt,sixforty=640,n; 


/* open printer */ 
DosOpen (dev_name, (PHFILE) &dev_hand, (PUSHORT) &dev_act,dev_size, 
dev_attr,dev_flag,dev_mode,dev_rsv) ; 
/* set spacing */ 
DosWrite(dev_hand,in_buffer3,bytesin3, (PUSHORT) &bytesout) ; 
/* set lines */ 
DosWrite(dev_hand,in_buffer4,bytesin2, (PUSHORT) &bytesout) ; 


blk_cnt=0; 
for(n=17;n <= 25;n++) 
{ 

N = blk_cnt * sixforty; /* block bytes */ 


/* 640 block */ 


ldarray (N,MM1) ; /* load array */ 

/* graphics mode */ 
DosWrite (dev_hand,in_bufferl1,bytesin1, (PUSHORT) &bytesout) ; 

/* print columns */ 
DosWrite(dev_hand,coli,bytesin, (PUSHORT) &bytesout) ; 

/* CR,LF */ 
DosWrite(dev_hand,in_buffer2,bytesin2, (PUSHORT) &bytesout) ; 


blk_cnt++; /* inc block count */ 
} 

DosClose (dev_hand) ; /* close printer */ 
} 


ldarray (N,MM1) 
UINT N; 
SEL MM1; 
{ 


extern BYTE MM[]; /* mask */ 
extern BYTE w[]; /* weights */ 
extern BYTE s[]; /* Gummy */ 
extern BYTE shift1[]; /* shift */ 


Figure 4.9b The routine pprtscr.c. 
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int n,n1,m,N4,row,col; 
extern BYTE coli[}; 


N4 = N/80; 
for(n = O;n <= 79;n++) 
{ 
for(m = O;m <= 3;mt+) 
coll[(n*4+m] = 0; 
for(nli = O;nl <= 7;n1++) 
{ 
row = N4 + nil; 
for(m = O;m <= 3;m+tt) 
{ 
col = n*4; 
s(m) = rbuf(row,col,MM1) ; 
} 
for(m = O;m <= 3;m++) 
{ 
s(m] (s{m] & MM[m]); 
s[(m] (s([m] >> shiftl[m]); 
s[(m] s{m) * w[{nl); 
col = n*4 + m; 
coll{col] = coll[{col] + s[m]j; 


} 


} 
rbuf (y,x,MM1) 
SEL MM1; 
int x,y; 
{ 
PCHAR 
UINT DM = 0x0000; 


ptr; 


if(y & 0x01) 
DM = 0x2000; 


ptr = MAKEP(MM1,DM + (80*(y >> 1)+(x >> 2))); 


return (*ptr) ; 
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column array */ 


block row */ 


initialize */ 


nearest byte */ 
screen byte */ 


mask */ 

shift rt */ 
weight */ 
column index */ 
column value */ 


selector */ 
x=col,y=row */ 


buffer ptr */ 
even/odd */ 
odd row */ 


byte pointer */ 
return value */ 


Figure 4.9b (Concluded) 


ores 


Figure 4.10 Representative sine wave 
output for the program prtwave.c. 
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ent threads call the same function. Hence in multithreaded applications the API 
services, which have code written for the multithreaded environment, are a more 
desirable way to write code than are the multithreaded versions of the standard C 
library routines. We always base our routines on the API calls. 

In general, the variety of memory management services is large. These serv- 
ices include DosAllocSeg(), DosSubAllocSeg(), and DosAllocShrSeg(). In the next 
section we consider the creation of a shared segment. This is among the more 
complex variants of segment manipulation and constitutes a useful example. Simi- 
larly, the creation of a process or thread can be contingent on synchronization. For 
example, if both a parent and a child process access a shared segment, some form 
of synchronization is needed to ensure that one process does not write over the 
results of another before the data is properly used. In general we achieve synchro- 
nization using semaphores. This approach, using semaphores for synchronization and 
the API services for multitasking, allows easy development of both non-reentrant 
and reentrant code in the OS/2 multitasking environment. Memory management is, 
of course, a subset of this activity, particularly when sharing segments. 


4.3.1 Creating and Accessing Segments 


A good example of the use of memory management is the creation and access of 
shared segments. Figure 4.11a is a flowchart for the program pipestc.c. This program 
is the C version of the assembly language program, pipest.asm, which appears in 
Figure 3.22b. The program sets up a shared segment, creates a pipe, uses sema- 
phores for synchronization, and passes a message to the pipe via the pipe’s buffer 
area. A child process, pipeclc.c, then reads the pipe message and prints the message 
to the screen. The process is shown in Figure 4.11b, and the code for the child 
process appears in Figure 4.12. The MAKE file for pipestc.c is illustrated in Figure 
4.13a, and the MAKE file for pipeclc.c is presented in Figure 4.13b. 

The program pipestc.c opens with four string expressions of CHAR type. 
These expressions define the pointers msg pd, prgm_nm, shrname, and asem1. 
Within the calling function, main(), a number of local variables have been defined 
using the standard OS/2 type casts. In the API service call to DosAllocShrSeg(), for 
example, the parameters are of the type 


SEL msell;: 
CHAR FAR *shrname; 
USHORT msize = 512; 


where USHORT = unsigned short (16-bit word) and SEL denotes a selector: un- 
signed short SEL. The actual call in DosAllocShrSeg() specifies that the selector, 
msel1, be specified as a pointer object: 


(PSEL) &msell 


Here the address of msell is treated as the pointer, as it should be. 
When DosMakePipe() executes a read handle and write handle are returned for 
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SETUP 
DATA 


CREATE 
SHARED SEGMENT 


PASS PIPE READ 
HANDLE TO SEGMENT 


CREATE 
SEMAPHORE 


WRITE 
MESSAGE TO PIPE 


PASS MESSAGE 
LENGTH TO SEGMENT 


SET 
SEMAPHORE 


CHILD 
PROCESS 
CREAT 
PROCESS #2 


WAIT CLEAR 
SEMAPHORE 


KILL 
PROCESS 


Figure 4.1la Flowchart for C program 
to emulate pipest.asm, a pipe and 
shared segment program. 


EXIT 
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/* Program to emulate pipest.asm -- pipestc.c 
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* This routine sets up a child and accesses a shared 
* memory segment. */ 


#define INCL_BAS 
#include <os2.h> 


E 


#include <string.h> 


CHAR *msg_p0 


CHAR FAR *prgm_nm 
CHAR FAR *shrname 


CHAR FAR *aseml 
blank[1] 


lmsg_p0; 


USHORT 
SEL 


HFILE 
USHORT 
USHORT 


USHORT 
HSEM 
LONG 


USHORT 
USHORT 


CHAR 
USHORT 
USHORT 
CHAR 
CHAR 


{0x0007}; 


msell; 


read_hdl,write_hdl; 


pflag = 256; 
bytes_ written; 


no_excl 1; 
sem_hdll; 
no_to = -1; 


freq = 5000; 
duration = 500; 


obj_nm_buf[40]; 
lobj_nm_buf = 40; 
async 1; 

argst 0; 

envst 0; 


RESULTCODES PIDD; 


PUINT 


USHORT 
USHORT 


USHORT 


ptr; 


action 
result 


error2; 


if(error2 != 0) 


print 
exit ( 
} 


f("Result code = 
1); 


$a",error2) ; 


"This is the OS/2 pipe message\n"; 
"PIPECLC. EXE"; 

"\ \SHAREMEM\ \SDAT1. DAT"; 

"\ \SEM\\SDAT. DAT"; 


Scroll attribute */ 
length result */ 


Shared buffer */ 
Buffer size */ 
Selector */ 


Pipe parameters */ 
Pointer to pipe handles */ 
Pipe size bytes */ 
Length of write */ 


Semaphore parameters */ 
No exclusive */ 
Semaphore handle */ 

No timeout */ 


Beep */ 
5,000 Hertz */ 
500 millisec */ 


Child process */ 

Failure buffer */ 

Length buffer */ 

Child asynchronous */ 
NULL command parm */ 
NULL environment parm */ 
Structure-result codes */ 


Pointer */ 


Terminate all threads */ 
Completion code */ 


Dummy error return */ 


Clear screen */ 


- /* Create shared segment */ 
error2 = DosAllocShrSeg(msize,shrname, (PSEL) &msel1) ; 


/* Check creation error */ 


Figure 4.11b Program code for pipestc.c, illustrated in Figure 4.11a. 
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/* Create pipe */ 
DosMakePipe ( (PHFILE) &read_hdl, (PHFILE) &write_hdl,pflag) ; 


ptr = MAKEP(msell,2); /* Pointer to 2nd word */ 
*ptr = read_hdl; /* Read handle */ 


/* Create system sem */ 
DosCreateSem(no_excl, (PHSEM) &sem_hd11, (PCHAR) asem1) ; 


DosBeep (freq, duration) ; /* Beep speaker */ 
lmsg_pO = strlen(msg_p0) ; /* Length of message */ 


/* Write to handle */ 
DosWrite(write_hdl, (PVOID)msg_p0,1msg_p0, 
(PUSHORT) &bytes_ written) ; 


ptr = MAKEP(msell,4); /* Pointer to 3rd word */ 
*ptr = bytes written; /* Length of write */ 


DosSemSet (sem_hd11) ; /* Set semaphore */ 


Initiate child */ 

error2 = DosExecPgm((PCHAR)obj_nm buf, 

lobj_nm_buf,async, 

(PCHAR) &argst, 

(PCHAR) &envst, 

(PRESULTCODES) &PIDD, 

prgm_nm) ; 

/* Check creation error */ 

if(error2 != 0) 


printf("Error on opening child"); 
exit(1); 
} 
DosSemWait (sem_hdl1,no_to) ; /* Wait on child */ 


/* Terminate child */ 
DosKillProcess (PIDD.codeTerminate, PIDD.codeResult) ; 


DosExit (action, result) ; /* Terminate parent */ 


{ 

USHORT ; top row */ 
USHORT ; left column */ 
USHORT ; bottom row */ 
USHORT ; right column */ 
USHORT li ; no. lines */ 
HVIO vio_hdl; handle */ 


/* Clear screen */ 
vVioScrollUp(tr,1lc,br,rce,no_line, (PCHAR) blank, vio_hdl) ; 
} 


Figure 4.11b (Concluded) 


the pipe. The read handle, read_hdl, is written into the second word of the shared 
segment. A semaphore is created to synchronize the parent and child process. Essen- 
tially, we want the parent to wait on the child process until the child completes its 
write to the screen. The parent process (pipestc.c) writes the message to the pipe 
buffer using DosWrite(), and a return count of the length of the message written is 
placed in the shared segment buffer at offset 4. Next, the semaphore is set and the 
child process started. Once the child completes, the semaphore is cleared and the 
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/* This is the child process -- pipecic.c 
* It writes the actual screen message using 


#define INCL_BASE 
#include <os2.h> 


CHAR FAR *aseml = "\\SEM\\SDAT.DAT"; 


CHAR FAR *shrname = "\\SHAREMEM\\SDAT1. DAT"; 
CHAR buffer[256]; 


USHORT action 
USHORT result 


HVIO vio_hdl; 
USHORT freq = 4000; 
USHORT duration = 500; 
HSEM sem_hdli; 

SEL shrsel; 

HFILE read_hdl; 


USHORT l1msg; 
USHORT bytes_read; 


USHORT FAR *ptr; 


DosOpenSen( (PHSEM) &sem_hdl1i1,asem1) ; 
DosBeep (freq, duration) ; 
DosGetShrSeg (shrname, (PSEL) &shrsel) ; 
ptr = MAKEP(shrsel, 2) ; 

read_hdl = *ptr; 


ptr = MAKEP(shrsel,4) ; 
lmsg = *ptr; 


OS/2 and C 


pipes */ 


Exit parameters */ 
Terminates all threads */ 
Completion code */ 

Video handle */ 

Beep */ 

4,000 Hertz */ 

500 millisec */ 

Semaphore handle */ 
Shared Segment Sel */ 
Read handle */ 


Length message */ 
Bytes read */ 


32-bit pointer */ 


Open semaphore */ 


Beep speaker */ 

Shared Segment */ 
Pointer to 2nd word */ 
Read handle */ 

Pointer to 3rd word */ 
Length of message */ 


Read message */ 


DosRead (read_hdl,buffer,1lmsg, (PSHORT) &bytes_ read) ; 


Chap. 4 


VioWrtTTy (buffer, 1msg,vio_hdl) ; /* Write message */ 


DosSemClear(sem_hdl1) ; /* Clear semaphore */ 


DosExit (action, result) ; 
} 


/* Terminate process */ 


Figure 4.12 Program code for child process, pipecic.c, used by pipestc.c. 
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pipestc.obj: pipestc.c 
cl -c -Zi -Os -FPc pipestc.c 


pipestc.exe: pipestc.obj 
link /CO pipestc.obj,pipestc,,\ 
slibce.1lib/NOE o0s2.1ib/NOE,, 


pipeclc.obj: pipeclc.c 
cl -c -Zi -Os -FPc pipeclc.c 


pipeclc.exe: pipeclc.obj 
link /CO pipeclc.obj,pipeclic,,\ 
slibce.lib/NOE os2.lib/NOE,, 


(b) 


Figure 4.13 (a) MAKE file for pipestc.c and (b) MAKE file for pipecic.c. 


wait state for the parent is terminated. The child process is terminated (along with 
any dependent processes), and the parent is completed with the termination 
DosExit(). The child process is illustrated in Figure 4.12. 


4.3.2 Creating a Thread or Process 


In Figure 4.11b the parent process initiates a child process specified using the 
pointer prgm_nm. This specification links the two processes and is the last parame- 
ter of DosExecPgm(). Figure 4.12 contains the program for the child. Note that the 
semaphore name and the shared segment name are the same as those specified by 
the parent. This constitutes the common link between the two processes. The speaker 
is beeped to indicate that the child is operating. The shared segment is retrieved and 
the pipe read handle and buffer length obtained. DosRead() is used to load buffer[] 
with the message in the pipe, and this message is printed using VioWvtTTY(. 

The return to the parent results in termination of the work semaphore. The 
child process is terminated by the parent, as well, with a full exit from the parent 
mode. Note that DosKillProcess() is not absolutely necessary because the child, 
pipeclc.exe, has been terminated but is good programming practice because it termi- 
nates all dependent processes started by the child, in addition to the child process 
itself, if needed. Figure 4.11b also illustrates the clear screen routine, which is a one- 
time call to VioScrollUp(). 

Figure 4.14 contains the MAKE file for a program ckthread.c, which creates a 
thread as opposed to a new process. Remember that a thread shares resources with 
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ckthred.obj: ckthred.c 
cl -c -Zi -Gs -FPc -F COO -Lp ckthred.c 


ckthred.exe: ckthred.obj 
link /CO ckthred.obj,ckthred,ckthred,slibce.lib/NOE os2.1lib/NOE,, 


Figure 4.14 MAKE file for ckthred.c. This program checks the formation of 
child threads. 


the subordinate or child threads. This is unlike creation of a new process, where 
each subordinate process has its own encapsulated resources. 

Since each thread has its own stack (a resource unique to the thread) a high- 
level-language compiler such as C will report stack overflow errors because the 
thread’s unique stack space does not overlap within a given process. This usually 
generates an error message (in the Microsoft C Optimizing Compiler Version 5.1, 
for example). To avoid such error messages, a compiler option, -Gs, can be used to 
eliminate stack checking only when the stack space is known to be sufficient [7]. 
This will allow the compilation of programs that generate separate threads without 
generating an error condition. Each thread should allow a minimum stack size of 
2048 bytes. In Figure 4.14 the compile and link allow generation of symbolic 
debugging information through options -Zi (compiler) and /CO (linker). 

Figure 4.15 illustrates a simple OS/2 C language program which generates a 
thread that prints the message 


“This is the subordinate thread” 


to the display. A second message is printed following completion of the child thread 
action and return to the parent calling thread. The latter thread prints the message 


“This is the main thread” 


Both threads generate 500-millisecond tones. Synchronization is achieved using 
semaphores. 

In the example program illustrated in Figure 4.15, no error checking exists 
following the API calls. This is because the program is fully debugged and the need 
for such diagnostics is minimized. During the debugging phase such diagnostics 
were included. Should a malfunction occur the user can, of course, set up such 
checking procedures. Note that in the call DosCreateThread(), the third parameter 
references byte 2047 in the stack as the stack start. This is because of the way the 
stack pointer is changed following a push to the stack. Element 2047 is the top of 
the stack in terms of address, and each push decrements the stack pointer to a lower 
address. Throughout this example the Toolkit nomenclature has been used. The type 
casting is in keeping with the Toolkit defined types and the actual API calls reflect 
the IBM Toolkit definitions for setup of the API functions. 
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#define INCL_BASE 
#include <os2.h> 


#include <string.h> 
#define SSIZE 2048 


FAR threadl1 (void) ; 


*msg_pl = "\n This is the main thread \n"; 

*msg_p2 = "This is the subordinate thread \n"; 

FAR *aseml = ™"\\SEM\\SDAT.DAT"; 

stack1(SSIZE]; /* Stack for threadl */ 
vio_hdl; 

sem_hdll; 


size_t lmsg_pl; 
size_t lmsg_p2; 


main() 


{ 
USHORT freq = 3000, duration = 500; 


USHORT action = 1, result = 0, no_excl 1; 
TID threadID; /* Thread ID */ 
LONG no_to = -1; /* no timeout */ 


DosBeep (freq, duration) ; /* Beep Speaker */ 

/* Create semaphore */ 
DosCreateSem(no_excl, (PHSEM) &sem_hd1i1, (PCHAR) asem1) ; 
DosSemSet (sem_hdl1) ; /* Set semaphore */ 
DosCreateThread (thread1, (PTID) &threadID, (PBYTE) &stack1[2047]); 
DosSemWait (sem_hd11,no_to) ; /* Wait thread */ 
lmsg_pl = strlen(msg_p1); /* Length Message 1 */ 
VioWrtTTy (msg_p1,1lmsg_p1,vio_hdl); 


DosExit (action, result) ; End main thread */ 


} 


void FAR threadi (void) 


{ 
USHORT freql = 5000, duration = 400; 


DosBeep(freq1, duration) ; Beep speaker */ 
lmsg_p2 = strlen(msg_p2) ; Length Message 2 */ 
vioWrtTTy (msg_p2,lmsg_p2,vio_hdl); _ Message 2 */ 


DosSemClear(sem_hdl11) ; Clear semaphore */ 
} 


Figure 4.15 The program ckthred.c, which creates and exercises a child thread. 
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4.4 OTHER PROGRAMS 


We have seen several examples of how to employ the API services in the C envi- 
ronment. These were beginning examples. In this section it will be useful to develop 
several more examples illustrating the lower-level nature of the API calls in this C 
environment. A great deal about the OS/2 implementation can be learned from these 
examples since frequently implementation features are obscured by the general 
syntax considerations. 


4.4.1 A Rotating Tetrahedron 


As a Starting point, consider two-dimensional space represented by the usual Carte- 
sian axes: x and y. Now consider the rotation of the point (x,, y,) to (x,, y,). Here, 
if r is the radius of the points from the origin 


x, = rcos(a,) (4.1) 
y, = rsin(a,) (4.2) 
and 
x, = r cos(a,) (4.3) 
y, = rsin(a,) (4.4) 
Writing 
a, = a+a, (4.5) 
we have 
( eS r cos(a + G,) 
= ( . ) (4.6) 
y, r sin(a + a,) 
which becomes 
xX, X, cos(a) — y, sin(a) 
= (4.7) 
y, x, sin(@) + y, cos(a) 


when the trigonometric identities are used for sine and cosine of the addition of two 
angles [4]. In matrix form 


X, x, Cos(a) — sin(a) x 


(4.8) 
y, y, sin(a) + cos(a) A 


This rotation can be extended to three dimensions, where 
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a : rotation angle about the x-axis 
B : rotation angle about the y-axis 
y : rotation angle about the z-axis 


and we obtain the rotation matrices (A, B, and C, respectively) appearing in Table 
4.1. Choosing an order to the rotation, we generate an overall three-dimensional 
rotation given by the matrix 


R=CBA (4.9) 


This matrix is indicated in Table 4.1 and will serve as the basis for rotation of the 
tetrahedron. Note that the three rotations in Equation (4.9) are not orthogonal. We 
would need to select a different set of rotation angles to ensure orthogonality. 


TABLE 4.1 ROTATION MATRICES FOR THREE-DIMENSIONAL MOVEMENT 


A 


1 0 0 cosB 0 sinB cosy -siny 0 
0 cosa -sina B = 0 1 0O C =] siny cosy 0O 
0 sina cosa -sinfp O cosB 0 0 1 


cosBcosy  sinasinBcosy—cosasiny cosasinfBcosy+sinasiny 
CBA =| cosfsiny Sina sinBsiny+cosacosy cosasinfB sin y—sin a cos y 
—sin B sina cos B cos a cos B 


If we have a point on the tetrahedron given by (x, y, z), it is possible to define a 
rotated point based on R using 


x, Xx 
(3) = R( » | (4.10) 
Z, Zz 


In this example the tetrahedron appearing in Figure 4.16 will be used and rotated 
using R. 

Figure 4.17 is the MAKE file for the rotating tetrahedron program. Note that 
pprtscr.c is not compiled in this MAKE file and we assume that an object module 
is available at link time. Figure 4.18a is the Structure Chart for this program. Fig- 
ure 4.18b illustrates a flowchart for tetra.c, the main program module. Figure 4.19 
contains the code for tetra.c. This module reads the three angular rates of rotation: 
>, B,, and y,. Also read in is a scale factor for the size of the display image and the 
number of iterations to be rotated. Each iteration assumes an effective time incre- 
ment of dt = 0.05 unit. 
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Figure 4.16 Three-dimensional starting representation for the tetrahedron. 


tetra.obj: tetra.c 
cl -c -Zi -Gs -FPc 


rotetra.obj: rotetra.c 
cl -c -Zi -Gs -FPc 


rotmat.obj: rotmat.c 
cl -c -Zi -Gs -FPc 


rotpt.obj: rotpt.c 
cl -c -Zi -Gs -FPc 


dmapoint.obj: dmapoint.c 
cl -c -Zi -Gs -FPc 


udmapoin.obj: udmapoin.c 
cl -c -Zi -Gs -FPc 


=F 


(0,0,1) 


coo 


coo 


coo 


coo 


tetra.c 


-Lp rotetra.c 


-Lp rotmat.c 


~Lp rotpt.c 


-Lp dmapoint.c 


~Lp udmapoin.c 


OS/2 and C 


tetra.exe: tetra.obj rotetra.obj rotmat.obj rotpt.obj \ 
amapoint.obj udmapoin.obj pprtscr.obj cgraph.lib 
link tetra+rotetra+rotmat+rotpt+dmapoint+tudmapoin+pprtscr,,,\ 
Slibce.1lib/NOE os2.1lib/NOE cgraph.1lib/NOE,, 


Figure 4.17 The MAKE file, tetra.mak, for the rotating tetrahedron. 
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000 
PROGRAM TO 
CREATE 
ROTATING 
TETRAHEDRON 


100 | 200 300 


INITIALIZE CALCULATE EXIT 
WINDOW ROTATED WINDOW 
TETRAHEDRON 


110 120 210 


220 


ROTATION SCALING AND GET TRANSLATE 
ANGLES NUMBER OF MESSAGE 


ITERATIONS 


MESSAGE 


Figure 4.18a Structure Chart for the rotating tetrahedron program. 


The module tetra.c contains the usual structures for VioSetMode(). After the 
display and physical buffer selectors are obtained, a call is made to r_tetra(), which 
sets up the new dynamic angle variables and calls rot_tetra(), which appears in 
Figure 4.20. Note that the arrays XX[], YY[], and ZZ[] are used to transfer the 
vertexes of the tetrahedron to rot_point(), where these points undergo the appropri- 
ate rotations. A call rot_mat() sets up the rotation matrix constants. The two func- 
tions DMA point() and uDMApoin() generate and remove the connecting lines, 
respectively. Figure 4.21 illustrates the calculation of the rotation matrix elements 
and should be compared with R in Table 4.1. Figure 4.22 merely completes Equa- 
tion (4.10). 

Figures 4.23 and 4.24 show the routines for accessing the physical screen 
buffer (DMApoint.c) and removing an existing dot on the screen (uDMApoin.c). 
They call wdot() and uwdot(), respectively, which are obtained from the library, 
ceraph.lib (see Figure 4.6). 

Figures 4.25a and 4.25b illustrate the rotating tetrahedron after 100 iterations 
and 50 iterations, respectively. The input values for rates of rotation are a, = B, = 
Y) = 1 and the scale is 60 units. These figures were obtained using prtscr(). 


4.4.2 Plotting Dow Jones Activity 


The major purpose of this example is to illustrate disk access under OS/2. We need 
to recognize that some activities that are performed using the API calls can also be 
performed using the default C library (run time). Disk access is one of these activi- 
ties. 
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SETUP 
DATA 


SET CGA 


CLEAR 
SCREEN 


LOCK 
SCREEN 


GET PHYSICAL 
BUFFER SELECTOR 


CACULATE AND PLOT 
ROTATED TETRAHEDRON 


PRINT 
SCREEN 


UNLOCK 
SCREEN BUFFER 


KEYBOARD 
HESITATE 


SET STD 
MODE 


Figure 4.18b Flowchart for tetra.c, 


etn the rotating tetrahedron program. 
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* The routine calls gphrout.c graphics functions. */ 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


struct _STRINGINBUF lkbd_buf; 
kbd_buf[80]; 


action = 0; 
error_code = 0; 
wait = 1; 


dstat[1]; 
dstat1[1]; 


XX[5] 
YY[5] 
2Z(5] 


X,Y,Z; 
scale; 
a[{10]; 
xx1(5],yy1[5]; 
xxx1[(5],yyy1[5]? 
dt = 0.05; 
int NTOTAL; 
float alpha,beta,gamma,alpha0,beta0,gamma0; 


col1[320]; 

MM([4] = {0x40,0x10,0x04,0x01 

w[8] = (128,64,32,16,8,4,2,1 
s(4]? 

shift1[4] = (6,4,2,0}; 
in_buffer1[4] {0x1B,0x4B,64,1); 
in_buffer2[2]} {O0x0D, Ox0A}; 
in_buffer3[3] {0x1B,0x41,8}); 
in_buffer4[2] {0x1B, 0x32); 
dev_name[5] = {'L','P','T','1', 


om~ it t to 


extern prtscr() 


SHANDLE vio_hdl 
SHANDLE kbd_hdl 
UINT wait2 = 1; 
SEL MM1; 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 


struct _VIOMODEINFO STDm; 


PVBPrt2.pBuf = (BYTE far *) (OxB8000) ; 
PVBPrt2.cb = 0x4000; 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 


Figure 4.19 Program code for tetra.c, the main calling program for the rotating 


tetrahedron. 


/* This program gener 


Conditional load */ 


keyboard buf len */ 
keyboard buffer */ 


end thread */ 
result code */ 
reserved word */ 


lock status */ 
lock status */ 


Coords tetra */ 


PrtSc routine */ 


video handle */ 
keyboard handle */ 
reserved */ 

dummy selector */ 


physical buffer */ 
CGA structure */ 


80 x 25 struct */ 


buffer start */ 
buffer size */ 


struct length */ 
CGA mode */ 
CGA color */ 
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CGAm.col = text columns */ 
CGAm.row = text rows */ 

CGAm. hres CGA hor res */ 
CGAm.vres CGA vert res */ 


STDm.cb = struct length */ 
STDm.fbType = 80 x 25 mode */ 
STDm.color = STD color */ 
STDm.col = 8 text columns */ 
STDm.row = 2 text rows */ 
sTDm.hres = STD hor res */ 
STDm.vres = STD vert res */ 


lkbd_buf.cb = 80; buffer size */ 


printf("Input x-rotation rad/sec \n"); 
scanf("%f", &alpha0O) ; 

printf("Input y-rotation rad/sec \n"); 
scanf("%f", &beta0) ; 

printf("Input z-rotation rad/sec \n") ; 
scanf("%f", &gamma0) ; 

printf("Input scale \n"); 

scanf("%f", &scale) ; 

printf("Input total no. iterations \n"); 
scanf ("%da", &NTOTAL) ; 


/* set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl); 


cclsCGA(vio_hdl) ; /* clear CGA screen */ 


VioScrLock(wait2,(char far *)dstat1,vio_hdl); /* lock screen */ 
/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl); 


= PVBPrt2.asel[(0]; /* selector */ 
r_tetra(MM1) ; /* tetrahedron */ 
prtscr (MM1) ; /* print screen */ 


VioScrUnLock(vio_hdl) ; /* unlock screen */ 
/* hesitate screen */ 
KbdStringIn((char far *)kbd_buf, 
((struct _STRINGINBUF far *) &lkbd_buf), 
wait,kbd_hdl); 
/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &STDm) ,vio_hdl); 
DosExit (action,error_code) ; 


} 


r_tetra(MM2) 
SEL MM2; 


{ 
int n; 


alpha x-angle 
beta y-angle 
gamma = 0; z-angle 


for(n = 1;n <= NTOTAL;n++) 
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{ dynamic angles */ 


alpha = alpha + alphaO#dt; 
beta = beta + beta0*dt; 
gamma = gamma + gamma0*dt; 


rot_tetra(alpha,beta,gamma,n-1,MM2) ; rotation */ 


Figure 4.19 (Continued) 
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} 
} 


cclsCGA(vio_hdl1) 
SHANDLE vio_hdli; 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 


PVBPrtl.pBuf = (BYTE far *) (OxB8000) ; /* phys buf start */ 
PVBPrtl1.cb = 0x4000; /* buffer length */ 


VioScrLock(waiti, (char far *)dstat,vio_hdl1l) ; /* lock screen */ 
/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll); 


MM = PVBPrtl.asel[0]; /* selector */ 
c1lrCGA (MM) ; /* CGA clear */ 


VioScrUnLock(vio_hdl11) ; /* unlock screen */ 
} 


c1rCGA (MM) 
SEL MM; 
{ 
INT n; 
INT N1 = Ox1F3F; end odd buffer */ 
INT DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= Ni;n+t+) 


{ 
ptr = MAKEP(MM,n); odd far pointer */ 
*ptr = 0; clear odd buffer */ 


for(n = O7n <= Ni;n++) 


{ 
ptr = MAKEP(MM, DM+n) ; even far pointer */ 
eptr = 0; clear even buffer */ 


Figure 4.19 (Concluded) 


Figure 4.26 presents a routine timhist.c that runs in Protected Mode and func- 
tions identically to its Real Mode counterpart. The program generates a disk file that 
serves as a time-ordered database. The program accepts three values per record: a 
month, a year, and a tabulated value. The library functions, called in this code 
correspond to the standard C library functions, which are reentrant, hence can be 
used for Protected Mode calls. For the example to be illustrated in subsequent fig- 
ures, this routine was used to create a database of monthly Dow Jones values be- 
tween January 1988 and December 1988. 
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/* Function to rotate tetrahedron */ 


#define INCL_BASE 
#include <os2.h> 


rot_tetra(alphal,betal,gammal,N,MM1) 


float alphal,betal,gammal; angles */ 

int N; 

SEL MM1; 

{ 

extern float XX[],YY[],22Z[]; Tetra points */ 
extern float x,y,2? point */ 
extern float scale; scaling */ 
extern float xx1[{],yy1[];: tetrahedron */ 
int n; 


if(N > 0) 

{ /* Clear tetrahedron */ 
uDMApoin(xx1[1],xx1{2],yy1[1],yy1[{2],MM1) ; 
uDMApoin(xx1[{1],xx1(3],yy1[(1],yy1[3],MM1) ; 
uDMApoin(xx1[(1],xx1[(4],yy1{1]),yy1[4],MM1) ; 
uDMApoin(xx1[2],xx1[(3],yy1[(2],yy1[(3],MM1) ; 

uDMApoin (xx1[(2],xx1[4],yy1[2],yy1[(4],MM1) ; 
uDMApoin(xx1[(3],xx1(4],yy1[(3],yy1[(4],MM1) ; 

) 


rot_mat(alphal,betal,gammal) ; /* load rotate */ 
for(n = 1l3n <= 43;n++) 
XX[n]); 


x = 
y = YY[(n]j; 
z= Z2Z[(n); 


rot_point(); 


xXxX1[n]) = x*scale + 150.; /* x-projection */ 
yyi({n) = y*scale + 100; /* y-projection */ 


} 
/* Rotate tetrahedron */ 

DMApoint (xx1[1],xx1[(2],yy1{1],yy1[2],MM1); 
DMApoint (xx1{1],xx1[3],yy1[1],yy1[3],MM1); 
DMApoint (xx1[1],xx1[4],yyl1(1],yy1[4),MM1); 
DMApoint (xx1(2],xx1[(3],yy1[2],yy1[(3],MM1); 
DMApoint (xx1{2],xx1(4],yy1(2],yy1(4],MM1) ; 
DMApoint (xx1[(3],xx1[4],yy1(3],yy1[(4],MM1); 
} 


Figure 4.20 The routine rotetra.c, which sets up the tetrahedron and calls the 
rotation matrices. 
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Figure 4.27 contains the MAKE file for dja.c, which reads the database created 


and generates a plot of the activity. In this case, this activity corresponds to the Dow 
Jones performance. Figure 4.28 presents the actual program code for dja.c. Note the 
needed API calls to clear the screen, plot the graphics, and print the screen. Figure 
4.29 is the prtscr() output for this Dow Jones time history. The curve consists of 
monthly values rounded to the nearest five points. 


The use of fprintf() constitutes the standard I/O call for the disk write and 


works as well in Protected Mode as in Real Mode. IBM and Microsoft have main- 
tained this standard I/O interface within the constraints of OS/2. 
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/* Function to calculate rotation matrix */ 
#include <math.h> 


rot_mat (alpha, beta, gamma) 
float alpha, beta,gamma; angles */ 


extern float a[]; rotation matrix */ 
double al,CA,CB,CG,SA,SB,SG; 


(double) (alpha) ; Sines & cosines */ 
cos(al); 

sin(al); 

(double) (beta) ; 

cos(al); 

sin(al); 

(double) (gamma) ; 

cos(al); 

sin(al); 


(float) (CB*CG) ; Matrix elements */ 
(float) (SA*SB*CG - CA*SG); 

(float) (CA*SB*CG + SA*SG); 

(float) (CB*SG) ; 

(float) (SA*SB*SG + CA*CG); 

(float) (CA*SB*SG - SA*CG); 

(float) (-SB); 

(float) (SA*CB) ; 

(float) (CA*CB) ; 


Figure 4.21 The program rotmat.c, which calculates the rotation matrix. 


/* Function to generate rotated point */ 


rot_point() 
( 

extern float x,y,2Z; /* point */ 

extern float a[]; /* rotation matrix */ 

float xl1,y1,zZ1; /* intermediate */ 


{1]*x + a[2]*y + a[3]¥*z; 
[4]*x + a[5]*y + a[6]*z; 
[7]*x + a[8]*y + a[9]¥*z; 


Figure 4.22 The program rotpt.c, which rotates a point. 
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/* This routine plots a connecting line using DMA */ 


#define INCL_BASE 
#include <os2.h> 


DMApoint (x1,x2,yl,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 


{ 

float m; 
int row; 
int col; 


if (xl == x2) 
m = 1000; /*Upper limit on slope*/ 
else 


m= (y2 - y1)/(x2 - x1); /7/* normal slope */ 
if(x2 > x1) 
{ 


for (col =(int) (x1)+1; col <= (int) (x2); col++) 
{ /* y-axis behavior */ 
row = (int) (yl + m*(col - x1)); 
wdot(col, row, MM1) ; /* write dot */ 
} 
} 


else 
{ 
if(x2 < x1) 


for(col =(int) (x2)+l;col <= (int) (x1); col++) 
/* y-axis behavior */ 
row = (int) (y2 + m*(col - x2)); 
wdot (col, row, MM1) ; /* write dot */ 
} 


} 
else 


col = (int) (x1); /* Vertical line */ 
if(yl > y2) 
{ 


for(row = (int) (y2)+lirow <= (int) (y1) ;row++) 
wdot (col, row, MM1) ; /* write dot */ 
} 
else 
{ 
for(row = (int) (yl)+l;row <= (int) (y2) ;row++) 
wdot (col, row,MM1) ; /* write dot */ 
} 


Figure 4.23. The program DMApoint.c, which writes a point on the display using DMA. 
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/* This routine removes a connecting line using DMA */ 


#define INC_BASE 
#include <os2.h> 


uDMApoin(x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 
{ 
float m; 
int row; 
int col; 


if (xl == x2) 
m = 1000; /*Upper limit on slope*/ 
else 
m= (y2 —- y1)/(x2 - x1); 7* normal slope */ 
if(x2 > x1) 
{ 
for (col =(int) (x1)+1; col <= (int) (x2); col++) 
{ 
row = (int) (yl + m*(col — x1)); 
uwdot (col, row,MM1) ; /* erase dot */ 
} 
} 


else 


{ 
if(x2 < x1) 


{ 
for(col =(int) (x2)+1;col <=- (int) (x1); col++) 


row = (int) (y2 + m*(col - x2)); 
uwdot (col, row, MM1) ; /*® erase dot */ 
} 
} 
else 
{ 
col = (int) (x1); /* Vertical line */ 
if(yl > y2) 
{ 


for(row = (int) (y2)+1l;row <= (int) (yl) ;rowt+) 
uwdot (col, row, MM1) ; /* erase dot */ 
} 
else 
{ 
for(row = (int) (y1)+lzrow <= (int) (y2) ;row++) 
uwdot (col, row,MM1) ; /* erase dot */ 


Figure 4.24 The program uDMApoin.c, which removes a point from the 
display using DMA. 
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Figure 4.25 (a) The tetrahedron after 100 iterations with and scale = 60. 
(b) The tetrahedron after 50 iterations with and scale = 60. 
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/* Routine to create time-history/value database -- timhist.c*/ 


#include <stdio.h> 


int month[288],year[288]; 
float value[288]; 
char FN1[(81]; 


main() 
{ 
int n,counter,check; 
FILE *outfile; 


printf("Input database filename \n"); 
gets (FN1); 

n= 1; 

month[0] = 1; 


while(month[n-1] != 0) 


printf("Input month as int (0 terminates) \n"); 

scanf ("%d", &month[n]) ; 

if (month[n] 
{ 


t= 0) 


printf("Input year as 2-digit int\n"); 
scanf ("%d", &year[n]); 
printf("Input value - floating point\n") ; 
scanf("%f", &value[n]) ; 
} 

n++; 

if(n > 288) 
exit(1); 


counter =n - 2; 
if((outfile = fopen(FN1,"w")) == NULL) 


{ 
printf("Output file failure: %s",FN1); 
exit(1); 


} 
fprintf(outfile,"%d ",counter) ; 
for(n = ln <= counter;n++) 


/* I/O file */ 


time arrays */ 
quant. interest */ 
filename array */ 


integer var. */ 
stream pointer */ 


library routine */ 
initialize index */ 
init month not 0 #/ 


increment index */ 
overflow mem */ 
fix count */ 


open out file */ 


/* output count */ 


fprintf(outfile,"%d %¢d *f ",month[n],year[n],value[n]) ; 


if((check = fclose(outfile) ) 
{ 
printf("Error in output file close") ; 
exit(1); 
} 


t= 0) 


/* close file */ 


Figure 4.26 The routine timhist.c, which creates a data file consisting of dates 


and values. 


dja.obj: dja.c 
cl -c -Zi -Gs -FPc -F COO -Lp dja.c 


dja.exe: dja.obj pprtscr.obj cgraph.lib 
link dja+pprtscr,,,\ 
slibce.lib/NOE os2.lib/NOE cgraph.1lib/NOE,, 


Figure 4.27 The MAKE file for dja.c, which plots the Dow Jones activity 


generated by timhist.c. 
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/* Routine to read Do 


#define INCL_BASE 
#include <stdio.h> 
#include <os2.h> 
#include <math.h> 
#include <stdlib.h> 


int month[288]},year[288]; 
float value([288)]; 

char FN1(81]; 

float xx[{1024}]; 

char buffer(90],buffer1[(90}; 


time arrays */ 
quantity */ 
filename array */ 
Scratch buffers */ 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


keyboard buf len */ 
keyboard buffer */ 


UINT action = 0; 
UINT error_code 0; 
UINT wait = 1; 


end thread */ 
result code */ 
reserved word */ 


CHAR dstat[1]; 
CHAR dstat1[1]; 


lock status */ 
lock status */ 


col1[320}; 

MM[4] = (0x40,0x10, 0x04, 0x01} 
w(8] = (128,64,32,16,8,4,2,1} 
s[{4]; 

shiftl[4] = (6,4,2,0}; 
in_buffer1[4] {0x1B,0x4B,64,1)}; 
in_buffer2[2] {0x0D, Ox0A} ; 
in_buffer3 [3] {0x1B,0x41,8}; 
in_buffer4[2] {0x1B, 0x32}; 
dev_name[5] = {'L','P','T','1',O}; 


e 
e 
e 
e 


int n,counter,check,N,i,delta,nmaxs,nmins; 
FILE *infile; 

double x,y,2; 

float maxt,mint,b,b1; 


integer var. */ 
stream pointer */ 


extern prtscr(); 


SHANDLE vio_hdl 
SHANDLE kbd_hdl 
UINT wait2 = 1; 
SEL MM1; 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 


struct _VIOMODEINFO STDm; 


PVBPrt2.pBuf = (BYTE far *) (OxB8000) ; 


PVBPrt2.cb = 0x4000; 


CGAm.fbType = 7; 
CGAm.color = 
CGAm.col = 40; 
CGAm. row = 25; 


Figure 4.28 The program dja.c, which plots the Dow 


print screen */ 


video handle */ 
keyboard handle */ 
reserved */ 

dummy selector */ 


physical buffer */ 
CGA structure */ 


80 x 25 struct */ 


buffer start */ 
buffer size */ 


struct length */ 
CGA mode */ 

CGA color */ 
text columns */ 
text rows */ 


Jones activity. 
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CGAm.hres = 320; 
CGAm.vres = 200; 


STDm.cb = 12; 
STDm.fbType = 
STDm.color = 
STDm.col = 80 
STDm. row 25; 

STDm.hres = 720; 
STDm.vres = 400; 


lkbd_buf.cb = 80; 
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CGA hor res */ 
CGA vert res */ 


struct length */ 


80 x 25 mode */ 
STD color */ 
text columns */ 
text rows */ 
STD hor res */ 
STD vert res */ 


buffer size */ 


printf("Input database filename\n") ; 


gets(FN1); 


library routine */ 


if((infile = fopen(FN1,"r")) == NULL) 


{ 


printf("Input file failure: %s",FN1); 


exit(1); 


fscanf(infile,"%d ",&counter) ; 
for(n = 1;n <= counter;n++) 


/* no. records */ 


{ 
fscanf(infile,"%d %*a *f ",&month[n], &year(n],&value[n)) ; 
printf("%5a %5d %6.0f \n",month[(n],year[n],value(n]) ; 


} 
if((check = fclose(infile)) != 0) 


printf("Error in input file close") ; 


exit(1); 
} 


mint 
maxt 


N = counter; 
for(i = 1;i <= N;i++) 
{ 
if(maxt < value[i)) 
maxt = value[i]; 
if(mint > value[i}) 
mint = value[i]; 
} 


delta maxt - mint; 
delta = delta/10; 


if(delta < 1) 
delta 1; 

if (delta 1 && delta < 5) 
delta 53 

if(delta 5 && delta < 10) 
delta 10; 

if(delta 10 && delta < 50) 
delta 50; 

if(delta 50 && delta < 100) 
delta 100; 

if(delta 100 && delta < 500) 
delta 500; 

if(delta 500) 


Viviviviviv de 


{ 
printf(" delta > 500"); 
exit(1); 
} 
nmaxs maxt/delta + 1; 
nnins mint/delta; 


Figure 4.28 


reverse limit */ 
reverse limit */ 


max/min */ 


Set scale */ 


(Continued) 
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maxt = delta*nmaxs; 
mint = delta*nmins; 
if(mint <= 0) 
mint = mint - delta; /* scaled min */ 


x = mint; /* scaled max */ 
y fabs (x) ; 
z (float) (y); 
bl = (2)/((float) (x)); 
if(maxt > z && bl < 0) 
mint = -maxt; 
else 


{ 
if(maxt < z && bl < 0) 


maxt = 2; 

} 
b = 150./(maxt - mint); /* plot coords */ 
for(i = 1;i <= N;it+) 

{ 

value[i] = 25. + (150. - b*(value[i] - mint)); 

xx[i] = 25. + (i - 1)*(256./(float) (N)); 

} 


/7/* CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far*) &CGAm) ,vio_hdl); 


cclsCGA(vio_hdl); /* clear screen */ 
VioScrLock(wait2, (char far *)dstat1,vio_hdl); /* lock buffer */ 


/* get physical buf */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl); 


MM1 = PVBPrt2.asel[0]; /* selector */ 


box_norm(MM1) ; /* plot box */ 


/* plot points */ 
for (n=1;n<=(N-1) ;n++) 
pltpt (xx[n],xx{nt+1],value[n],value(n+1],MM1) ; 
prtscr(MM1) ; /* print screen */ 


VioScrUnLock (vio_hdl) ; /7* unlock buffer */ 


KbdStringIn((char far *)kbd_buf, /* hesitate */ 
((struct _STRINGINBUF far *) &lkbd_buf), 
wait, kbd_hdl); 


/* STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *)&STDm) ,vio_hdl) ; 


DosExit (action,error_code) ; 


} 


box_norm(SEL MM) 


{ 
int xxbeg,xxend, yybeg, yyend; 


xxbeg /* box parameters */ 
xxend 
yybeg 
yyend 


=e 


NN 
oun 
~ 
=e 


253 
175; 


bboxx (xxbeg, xxend, yybeg, yyend, MM) ; /* draw box */ 
} 


Figure 4.28 (Continued) 
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cclsCGA(SHANDLE vio_hd1l1) 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 


PVBPrtl1.pBuf = (BYTE far *) (0xB8000) ; /* phys buf start */ 
PVBPrtl1.cb = 0x4000; /* buffer length */ 


VioScrLock(wait1, (char far *)dstat,vio_hdl1); /* lock screen */ 


VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdl1); 


MM = PVBPrtl.asel[(0]; /* selector */ 
C1rCGA (MM) ; /* CGA clear */ 


VioScrUnLock(vio_hd1}1) ; /* unlock buffer */ 
} 


clrCGA(SEL MM) 
{ 
int n; 
int N1 Ox1F3F; end odd buffer */ 
int DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= Nl1;n++) 


{ 

ptr = MAKEP(MM,n) ; odd far pointer */ 
*ptr = 0; Clear odd buffer */ 
} 


for(n = O;n <= N1;nt+) 
{ 
ptr = MAKEP(MM, DM+n) ; even far pointer */ 


*ptr = 0; clear even buffer */ 
} 


Figure 4.28 (Concluded) 
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Figure 4.29 Annotated plot of Dow Jones activity through the October 1987 
crash. 
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4.5 SUMMARY 


This chapter has served to illustrate the OS/2 and C programming language inter- 
face. C represents a higher degree of abstraction than does assembler. The IBM 
Toolkit provides a complete set of types and API function prototypes to permit high- 
level access to the API services. The low-level nature of these services is illustrated 
in the C context. 

Graphics under C are developed and a new print screen routine in C is pre- 
sented that allows a screen dump in graphics mode. This screen dump program is 
designed for operation with CGA mode. The standard C syntax is presented and a 
knowledge of this syntax is assumed as a prerequisite to understanding the chapter. 

The creation of multitasking routines is developed using multiple threads and 
processes. Finally, the issues associated with programming multitasked routines in C 
are developed through program examples. This chapter is necessarily introductory 
and establishes a basis for programming OS/2 applications using the C language. 
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PROBLEMS 


4.1 When using the IBM Toolkit definitions, what precaution must be used between Ver- 
sions 1.0 and 1.1? 

4.2 What are the implications for the standard C I/O library running under the Protected 
Mode of OS/2? 

4.3. The Version 5.1 of the Microsoft C Optimizing Compiler passes formal parameters 
with type specifications for these parameters appearing in the function definition. 
Typically, a function definition such as 
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4.4 
4.5 


4.6 


4.7 
4.8 


4.9 


4.10 
4.11 


4.12 
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INT box _norm(waitt, float x, float y) 


replaces 


INT box_norm(waitt, x, y) 
INT waitt; 
float x,y; 


The type specification moves within the formal parameter list itself. What characteris- 
tic of this type definition remains consistent across formal parameter types? 


In Figure 4.1, why must the input word integer be less than 32,768? 


The OS/2 references dictate the manner in which the API services must be loaded on 
the stack. Using the normal C calling convention, what parameter access on the local 
stack exists? How does the Toolkit modify the API calls to load the local stack cor- 
rectly for access? 


What does the syntax 
CHAR FAR *ptr; 


mean? Why is the following acceptable? 


CHAR FAR *shrname = “\\SHAREMEM\\SDAT1.DAT”; 


What does the function MAKEP (sel,off) accomplish? 
In Figure 4.5b, what is the significance of the following? 


PVBPrt2.pBuf = (BYTE far *)(0xB8000); 
What is wrong with the code 


float y; 
double t; 


y = sin(2.* PI *t); 
Assume that PI is defined as 


#define PI 3.141592654 


What differentiates uwdot() from wdot()? (See Figure 4.6.) 
In pltptQ) and upltptQ (Figure 4.6) the x-values are associated with column values and 
the y-values are associated with row values. Explain. 


In setting up the printer for a dump of the display, the following command is used 
(Figure 4.9b): 
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4.13 


4.14 
4.15 


4.16 


4.17 
4.18 
4.19 
4.20 


4.21 


DosWrite(dev_hand,in_buffer,bytesin1l, (PUSHORT) &bytesort) ; 


Here bytesin1 = 4 and 
BYTE in_bufferl[4] = {0x1B,0x4B,64,1}; 


What is the significance of this output value? 


What is the meaning of the DosWrite() execution in Figure 4.9b with in_buffer3[] 
defined as 


BYTE in_buffer3[3] = {0x1B,0x41,8}; 


In Figure 4.11b, are the semaphores used RAM semaphores or system semaphores? 


What is characteristic about all the API function calls and their associated formal 
parameters? 


What is the generic mechanism used by the semaphore calling sequence to ensure 
synchronization between two processes? Between two threads? 


In Figure 4.12, what is the purpose of accessing the shared segment? 
When creating a thread within a process, how is the thread’s stack handled? 


Throughout the examples of this chapter, error checking for such actions as creating a 
thread have been deleted from the basic code. Please comment on this lack of error 
checking intrinsic to the programs. 


In the program tetra.c (Figure 4.19), what are the basic vertex points used for the 
tetrahedron? 


In Figure 4.28, where does the routine dja.c acquire the function bboxx()? 


5 Additional OS/2 
Considerations 


In Chapter 4, C programming for the OS/2 full-screen mode was presented. We saw 
that the C code required low-level access for many operations that call API func- 
tions. C has the advantages afforded high-level languages as well as low-level ac- 
cess to the operating system via these API services. Hence C is an ideal candidate 
language for programming OS/2. Occasionally, a need will exist for generating a 
special-purpose routine in assembly language and interfacing it to C program code. 
The methodology for accomplishing this is discussed in Section 5.1. 

The Microsoft linker, which comes with the C compiler utilities, serves to load 
and link the object modules required by a program. When an .exe program is gen- 
erated by the linker, all needed object modules must be input to the link process. 
This can be cumbersome, especially when large library files are called by the linker. 
OS/2 possesses the capability for two types of dynamic linking using dynamic 
linked libraries (DLL), where external references can be resolved by means other 
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than the static linking normally employed. DLL satisfy external references either 
during loading, load-time linking, or at run-time, run-time linking. In the former case 
all external references are satisfied by the linker through knowledge of where the 
DLL routines reside. In this case a priori knowledge about the location of the 
needed DLL routines exists even though these routines are not located within the 
.exe module at linking. When a program begins execution the DLL routines are 
loaded, when called, based on this knowledge of where these routines reside. In run- 
time linking, the DLL routines are located at the time they are called and then 
loaded. The latter approach takes slightly longer than load-time linking but leaves 
the basic executable module unencumbered. 

Why would OS/2 implement dynamic linked libraries? Primarily because of 
the multitasking feature. Since multitasking and memory management require move- 
ment into and out of memory, it is desirable to keep executable modules as small as 
possible. DLL management is one technique for achieving small executable modules. 
In Section 5.2 we address DLL implementation. In the remainder of the chapter we 
consider programming conventions, take a brief additional look at the API, and 
study a representative C example. 


5.1 MIXED-LANGUAGE PROGRAMMING AND OS/2 


We have seen how both assembly language and C code can be used for program- 
ming under OS/2. C code is preferred as the level of abstraction or task complex- 
ity increases. C, however, yields less optimized object code than does assembly lan- 
guage programming. Hence for critical applications, C routines must be interfaced 
to assembly language modules. This is particularly true when hardware is to be 
accessed directly or execution speed is important. In this section, where we address 
the integration of C and assembler, we will assume that the C modules call assem- 
bler modules when appropriate. 
Assembler has a basic template for setup to interface to Microsoft C: 


TITLE... 
; ‘ 
; Description... 


a 
_DATA1 SEGMENT BYTE PUBLIC ‘DATA’ 
PUBLIC _VARI,... 


_DATAI1 ENDS 
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_ TEXT SEGMENT BYTE PUBLIC ‘CODE’ 
ASSUME CS:_TEXT,DS:_DATA1 
PUBLIC _Function* 
_Function PROC NEAR 
PUSH BP 
MOV BP,SP 
SUB SP,10 
PUSH BX 
PUSH CX 
PUSH DX 
PUSH SI 
PUSH DI 


PUSH DS 
MOV AX,SEG _DATAI 
MOV DS,AX 
(main body) 
MOV AX,..- 
POP DS 
POP DI 
POP SI 
POP DX 
POP CX 
POP BX 
MOV SP,BP 
POP BP 
RET 
_Function ENDP 
_TEXT ENDS 
EMD 


To interpret this template, consider first the segment definitions. Two segments 
are defined: TEXT and DATAI, the code segment and the data segment, respec- 
tively. The data segment is not_ DATA because all parameters from the calling data 
segment will be passed using the stack. Hence there is no need to keep the “old” 
data segment during execution of the assembler code. The new segment, DATAI1, 
is optional as needed. Following definition of the segment registers using ASSUME, 
a procedure, Function, is defined. This function must be PUBLIC so that it can be 
called externally. Upon entry to the procedure, a return address will be pushed on 
the stack. This address is an offset (2 bytes) for NEAR calls. After the call the 
calling routine has its frame pointer in the BP register. This pointer serves as the 
basis for moving from frame to frame. The template requires pushing this address on 
the stack. Four bytes now reside on the stack for a NEAR call. The stack pointer 
now contains the new frame pointer, which is loaded into BP, and space is allocated 
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on the stack by advancing the stack pointer 10 bytes (as an example). These steps 
are accomplished with the code 


PUSH BP 
MOV BP,SP 
SUB SP,10 


Next, the general-purpose registers (except AX) and the index registers are pushed 
on the stack. Finally, the old data segment address (appearing in DS) is saved on the 
stack and a new data segment address for DATAI is loaded into DS. 

The parameters passed to the assembler reside starting at [BP+4] because a 
return address and a frame pointer have been loaded. Assuming that all parameters 
are of type int, they will reference as [BP+4], [BP+6], [BP+8], and so on. Clearly, 
other data types will occupy space accordingly. The return values from the assem- 
bler routine will occupy AX or AX and DX. At this point all pushed registers are 
popped, the caller’s frame pointer restored, and the return address accessed. This, 
then, briefly describes the template for interfacing assembler to C. 

Figure 5.1 illustrates a C program that reads an upper and lower frequency, a 
number of iterations, and an individual tone duration (in milliseconds). The program 
generates a musical or tone scale at intervals of 100 Hz for the range of frequencies 
spanned by the upper and lower frequencies. This C program calls an assembly 
language routine, scales1(), which accesses the tone generator. This assembly lan- 
guage routine appears in Figure 5.2 and follows the normal assembly language 
template for the C interface [1]. Note that the main portion of this routine simply 
passes the formal parameters to @DosBeep. In this case the frequency, freq, is 
passed at [BP+4] and the duration, dduration, is passed at [BP+6]. The inclusion 


IF1l 
include sysmac.inc 


ENDIF 


loads the API services as required. 


The routine scalesl.asm, which appears in Figure 5.2, was assembled with the 
instruction 


masm scalesl 

The C program appearing in Figure 5.1 was compiled using 
cl -c -—Zi; scales.c 

The linking was accomplished as 


link scales+tscalesl1, scales,,doscalls,,,/CoO 
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/* This program generates scales and 
* calls an assembler routine */ 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


UINT low_freq,high_freq,no_iterations,dduration; 


UINT action = 0; 
UINT error_code = 0; 


main() 
{ 


printf("Input lower frequency (Hz) - integer\n") ; 
scanf ("%$d", &low_freq) ; 

printf("Input higher frequency (Hz) -- integer\n") ; 
scanf ("%td", &high_ freq) ; 

printf("Input number iterations \n") ; 

scanf ("%d",&no_iterations) ; 

printf("Input component duration \n"); 

scanf ("%d", &dduration) ; 


sscale(); tone generator */ 


DosExit (action,error_code) ; 
} 


sscale() 


{ 
extern scalesi1(); assembler module */ 


int freq,n,m,N; 


low_freq = low_freq/100; normalize */ 


low_freq = low_freq * 100; 
if(low_freq <= 100) 
low_freq = 200; minimum set */ 


high_freq = high_freq/100; normalize */ 
high_freq = high_freq * 100; 


m 0; initialize loop */ 
N (high_freq - low_freq)/100; no. tone points */ 


while(m <= no_iterations) check limit */ 
{ 
for(n = 1l;n <= N;n++) up-scale */ 
{ 
freq = low_freq + n *100; set frequency */ 
scales1(freq,dduration) ; tone */ 


for(n = 1;n <= N;n++) down-scale */ 
{ 
freq = high_freq - n * 100; set frequency */ 
scales1(freq,dduration) ; tone */ 
} increment loop */ 
m++}; 


} 


Figure 5.1 C program to generate musical scale based on input frequencies and 
time duration. 7 
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PAGE 40,132 

TITLE scalesl - Routine to generate scales (saclesl.asm) 
DESCRIPTION: This routine generates various tones. 
(BP+4] contains the frequency and [BP+6] contains 
the duration in millisec. 


; 
; 
; 
IF1l 


include sysmac.inc 
ENDIF 


_TEXT SEGMENT BYTE PUBLIC 'CODE' 
ASSUME CS:_TEXT 
PUBLIC _scalesl 

_scalesl PROC NEAR 


push BP 
mov BP,SP 
sub SP,8 
push DI 
push SI 
push AX 
push BX 
push CX 
push DX 
;Begin beep 
@DosBeep [BP+4], [BP+6] 
pop DX 
pop Cx 
pop BX 
pop AX 
pop SI 
pop DI 
mov SP,BP 
pop BP 


ret 
_scalesl 
_TEXT ENDS 

END 


Figure 5.2 C-callable assembly language routine to generate tonals. 


5.2 DYNAMIC LINKING AND RESOURCE MANAGEMENT 


Dynamic linking is a method of generating an executable program where not all 
modules are loaded into the execute file at link time but are loaded on demand 
during execution [2]. Under OS/2 a single code segment can be accessed by mul- 
tiple programs, and such reentrant code facilitates dynamic linked library (DLL) 
usage, where simultaneous access of a library routine is possible. This is in keeping 
with the goal of minimizing code in a multitasking environment. 

The two types of dynamic linking, load-time linking and run-time linking, 
serve distinctly different needs. Load-time linking involves complete knowledge of 
where a needed external routine resides prior to execution and is appropriate for fre- 
quently used routines. Run-time linking requires locating and installing external 
routines upon their call from an executing program. This form of linking is used 
primarily for accessing routines on an infrequent basis. 
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5.2.1 Using Dynamic Linked Libraries 


We have seen that dynamic linked libraries (DLL) are useful when it is desirable to 
minimize the amount of code linked with multiple executable routines or tasks in a 
multitasking environment. It is in support of multitasking that DLL can contribute 
significantly. The run-time dynamic linking circumvents this situation where a DLL 
can be released from an executable module. | 

There are actually three types of linked modules possible when dynamic link- 
ing is employed: 


1. Load-time dynamic Linking 
a. Preloaded DLL 
b. Load on Call DLL 

2. Run-time dynamic Linking 
a. Explicit Load and Call 


To fully appreciate the nuances among these options, we must examine the concept 
of a definition file, where one of these options is determined for each DLL imple- 
mentation. Briefly, the preloaded DLL requires that these DLL routines be loaded at 
the start of execution. The load on call DLL implies that the code be loaded as each 
DLL routine is called by the executing program using guidance in the definition file. 
Finally, the explicit load and call situation for run-time dynamic linking requires that 
the DLL be accessed using API services. We will consider each type of DLL access 
in Section 5.2.4. 

The LINK utility is used to join object routines into executable modules that 
have all their external references accounted for. The linker is used to create either 
a DLL or an executable, .exe, file. How does this work? Basically, the module 
definition file (.def) specifies whether or not a particular output (from the linker) is 
to be a DLL or an .exe file. This definition file also includes a number of statements 
that can be used to tailor executable code to accomplish various optimizations. It in- 
cludes information that distinguishes between a DLL or application, a list of im- 
ported and exported functions (see below), the size of the stack and heap, and a 
number of options for the code and data segments. The latter option allows speci- 
fication of whether or not segments are to be preloaded or loaded on demand. When 
using the linker we have noticed that a prompt for a definition file always occurs as 
the last entry in the linker prompt sequence. So far we have left this entry blank, 
which is an appropriate default for applications. We will now use this prompt to 
supply a .def file where appropriate. 


5.2.2 The Definition File 


Table 5.1 illustrates the allowed (and in some cases the mutually exclusive) state- 
ments that can appear in the module definition file. The first two statements are 
either NAME or LIBRARY. The former specifies the name of an application (.exe) 
and the latter specifies the name of a DLL (.dll). The description (DESCRIPTION) 
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merely states in prose the module purpose. The statement PROTMODE specifies 
that a module is to run under Protected Mode. The statement 


CODE [load] [shared] [execute] [privilege] 


is used to define the default attributes for all the module’s code segments. Subse- 
quent statements using the SEGMENTS key word can override this statement 
(CODE) to tailor segment usage. In the CODE statement above, [load] is used to 
specify whether or not the code segments are physically loaded at the start of exe- 
cution or on demand. This option has two possible values: PRELOAD (for loading 
at start of execution) and LOADONCALL (for demand loading). 

The next option, [shared], specifies whether code segments in a DLL are to be 
accessed by all tasks needing these segments as a single instance or as multiple 
instances (where duplicate copies of the DLL routine are generated). This option has 
two possible values: SHARED (where only one copy of the code segment exists) or 
NONSHARED (where a unique copy of the code segments is loaded for each ref- 
erence). The option [execute] allows code segments to remain distinct through the 
value EXECUTEONLY. In this case the code segment selector cannot be loaded 
into DS. The alternative value, EXECUTEREAD, permits the segment selector to be 
loaded into DS. Finally, [privilege] is used to give code segments I/O privilege at 
level 2 by having IOPL specified. 


TABLE 5.1 MODULE DEFINITION FILE STATEMENTS 


Statement Comments 
NAME Declares a module as an application 
LIBRARY Declares a module as a DLL module 
DESCRIPTION Defines module descriptively 
PROTMODE Declares a module as a Protected Mode routine 


CODE [load][shared][execute][privilege] 


[load]: specified whether code loaded at the start of execution 
(PRELOAD) or on demand (LOADONCALL) 

[shared]: one copy of code loaded (SHARED) or multiple 
copies loaded with tasks (NONSHARED) 

[execute]: (EXECUTEONLY)—code segments can only be 
executed; or (EXECUTEREAD)—they can be read as well 

[privilege]: allows code segment I/O capability 
(IOPL) 

DATA [load][instance][shared][write][privilege] 

[load]: specifies whether code loaded at the start of execution 
(PRELOAD) or on demand (LOADONCALL) 

[instance]: no automatic data segment created (NONE), all 
instances share the same automatic data segment 
(SINGLE),and multiple copies for each instance (MULTI- 
PLE) 

[shared]: same copy of a segment shared (SHARED) and new 
copies loaded for each instance (NONSHARED) 
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TABLE 5.1 (Concluded) 


Statement Comments 


[write]: specifies that a memory segment can be written to 


(READWRITE) or only read (READONLY) 
SEGMENTS [segname][CLASS(‘classname’)][minalloc][segflags] 
[segname]: name of segment whose attributes are to be 
changed 


[classname]: ‘CODE’ or ‘DATA’ 
{minalloc]: minimum number of bytes reserved for segment 
[segflags]: attributes assigned to segment 


IMPORTS {intname]modulename.[entryname or entryordinal] 
{intname]: name to be used within importing module 
modulename: application library that contains functions 
{entryname]: entry point to DLL routine 
{[entryordinal]: DLL routine ordinal position 


EXPORTSentryname[=intname][@ordinal][RESIDENTNAME][NODATA]Jargnum 

entryname: name to be used by accessing routines 

[intname]: real name of routine 

[@ordinal]: defines the routine’s ordinal value within export 
module 

[RESIDENTNAME]: used with @ordinal argument to specify 
resident always 

[NODATA)]: if present, specifies no stack or automatic data 


segment 
argnum: number of parameters to be received or IOPL 
STACKSIZE Number of bytes an application or DLL needs for its own 
stack 
HEAPSIZE Number of bytes in application or DLL heap 
STUB Name of a DOS 3.x program to replace an application or 


library invoked in Real Mode instead of correctly specify- 
ing Protected Mode 


The statement 
DATA [load] [instance] [shared] [write] [privilege] 


is used to specify the default attributes for all the module’s data segments. The first, 
[load], is the same as for the CODE statement except that LOADONCALL is the 
default option when no load argument is specified. The option [instance] describes 
the automatic data segment, which is the physical segments(s) represented by the 
name dgroup. This segment(s) contains the local heap and stack area for an appli- 
cation. It can take one of three values: NONE (no automatic segment), SINGLE (all 
application instances share the same automatic data segment), and MULTIPLE (de- 
fault value where each instance has its own automatic data segment). 

The argument [shared] parallels the [instance] value. It has two values: 
SHARED (same copy of a segment is shared by multiple instances of an applica- 
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tion) and NONSHARED (new copies of data segments are loaded for each instance 
of an application; this is the default value). The [shared] argument and the [in- 
stance] argument must match. If a conflict arises, all segments in dgroup are shared, 
and all others are nonshared. 

The argument [write] specifies whether the data segments can be written to or 
not: READONLY (cannot be written) and READWRITE (default option; the seg- 
ment can be written to as well as read). The argument [privilege] is the same as for 
CODE. The statement 


SEGMENTS ; 
[segname ][CLASS( ‘classname’ yiminalieey eagtiagas 


is used to assign attributes individually to code ¢ or data segments. The parameter 
[segname] denotes the segment label and can be declared as ‘CODE’ or ‘DATA’ via 
the classname. The default is ‘CODE’. Each segment is allocated a minimum 
number of bytes: [minalloc]. The argument [segflags] can be any combination of 
arguments specified above with CODE or DATA segments. 

The form of the IMPORTS statement is 


IMPORTS 7 
[intname] modulename. [entryname|entryordinal ] 


Here intname specifies the internally used name of the importing module as it calls 
an external entry point (the ASCII string, entryname, within the DLL). The parame- 
ter modulename is the name of the application or DLL containing the needed func- 
tions, and entryordinal merely identifies entryname by its ordinal position with the 
DLL. 

The form of the EXPORTS statement is 


EXPORTS 
entryname[=intname ] [@ordinal ] [RESIDENTNAME ] [NODATA]argnum 


This statement defines the routines within a DLL or application that are to be 
available for other programs. Alternatively, it can be used to specify routines that are 
to have level 2 I/O privileges. The argument entryname defines the name that call- 
ing modules will use when accessing the exported routine. The parameter [=intname] 
is the real name appearing in the exporting routine. The [@ordinal] parameter de- 
fines the routine’s ordinal value within the module. 

The argument [RESIDENTNAME] is used only when [@ordinal] is specified 
and it indicates that the function’s name must be resident at all times and, conse- 
quently, the name and ordinal value will be stored in the DLL export table. The 
[NODATA] argument means that the export routines will have neither a stack nor 
an automatic data segment. Finally, argnum takes on the value IOPL when the ex- 
port routine is to have level 2 privilege. 

STACKSIZE specifies the number of bytes an application or DLL needs for 
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the local stack. Similarly, HEAPSIZE specifies the number of bytes an application 
or DLL needs for its local heap. STUB specifies the name of a DOS executable file 
to be run in place of a Protected Mode application or library when such applications 
or libraries are invoked under Real Mode. 


5.2.3 Creating a DLL 


In the preceding section we saw examples of the use of IMPORT and EXPORT in 
the definition file. IMPORT specifies the routines that will be used by an executable 
file and incorporated at load or run time, as indicated in the application definition 
file. EXPORTS specifies the routines that will be transferred to the executable file 
at load or run time from the DLL, as indicated in the DLL definition file. 

To see this work, consider the creation of a DLL and its incorporation with 
other modules. The following sequence of steps corresponds to Example 1 in Sec- 
tion 5.2.4, where the program code will be specified: 


link dyninit.obj dlinkl.obj, dynll.dll, doscalls.lib, dynll,def 


This link statement links dyninit and dlink1 (both object modules) to create dyn11. 
We assume that dyn11.def has the LIBRARY option with dyn11 specified. Then the 
created routine has the .dll extension, denoting it as a dynamic linked library. The 
single library, doscalls.lib, imports the API service routines. Hence, from the fore- 
going process comes the DLL, dyn11.dll. 

Dynamic linked libraries must be linked with applications as libraries, not .dll 
files. Hence the import library utility, implib, can be used to create this library based 
on the definition file. The routines above, for example, are in dyn11.dll, but the 
entry points can be specified in dyn11.lib, which is created as follows: 


implib dynll.lib dynll.def 


Here implib creates dyn11.lib, which has the entry points specified by the EXPORT 
table in dyn11.def. 

The last step is to create the application run file and satisfy all external refer- 
ences through library access (as an example). Assume that the application exists as 
an object module named dyn1.obj. The link procedures will be 


link dynl.obj, dynl.exe,,doscalls.lib dynll.1lib,, 


Here dynl.exe is the output for dynl.obj and uses both doscalls.lib (the API serv- 
ice) and dyn11.lib (the library file for the DLL). During execution of dynl.exe the 
DLL routines will be accessed via the dyn11.lib table (these DLL routines reside in 
dyn11.dll). 

The importance of specifying EXPORT and IMPORT files should now be 
clear. It is the only way of identifying DLL routines to the implib utilities that create 
the DLL needed library file. This file points to the available DLL routines (this file 
is output from implib with extension .lib). 
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5.2.4 DLL Examples 


In the preceding section we outlined how to create a DLL using an appropriately 
constructed module definition file. Both the link and implib utilities were used in 
this process. File names were specified without actually presenting the files them- 
selves, in order that the mechanics of the linking process could be illustrated. By 
way of introducing an example, the code is now presented for the files in question. 


Example 1. Figure 5.3 shows the main application program, dynl.asm, which 
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TITLE DYN1 - Main calling program example #1 (dynl.asm) 


; DESCRIPTION: This program calls dynil.dll to demonstrate 
; preloaded assembler dynamic link libraries. 
; 


-286c 
-sall ;Suppresses macro lists 


-xXlist 
INCL_BASE equ 1 
include OS2.INC 
-list 


extrn dlink1:FAR 
dgroup GROUP data ;defines automatic data seg 


; 

STACK SEGMENT PARA STACK 'STACK' 
db 64 dup('STACK *) 

STACK ENDS 


; 

data SEGMENT PARA PUBLIC 'DATA' 

; 

msg1 ‘Dynamic Link Pre-loaded Routine',0ODH, OAH 
msg1_1 &-msgl 

msg2 'Error on access DLL',0ODH, OAH 

msg2_1 $-msg2 


action 0) scode to end thread 
result ie) sreturn code for error 
vio_hdl 0 ;video handle 


data 


CSEG SEGMENT PARA PUBLIC ‘'CODE' 
ASSUME CS:CSEG,DS:dgroup 
DYN1 PROC FAR 


push ds ;push message segment 
lea bx,msg ;offset of message 
push bx ;save offset 

push msgl1_1 message length 


call dlinkl ;DLL routine to print msg 


cmp ax,0 ;check for error 
je EXIT ;jump if OK 
@VioWrtTTY msg2,msg2_1,vio_hdl 


e 
a 


@DosExit action, result 
ENDP 

ENDS 

END DYN1 


Figure 5.3 Main dynamic link library calling program, illustrating preloaded 
DLL routines. 
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imports routines from the DLL. It is this file that must be linked with doscalls.lib 
and dyn11.lib to create the application executable module. The data segment for this 
module is named data and the code segment is CSEG. In the figure three values are 
pushed to the stack: first, the data segment address for data; second, the offset 
address for msg1; and finally, the length of msgl1 is pushed. These values will 
eventually be accessed using a structure (template) and the stack starting address. 
During a push operation a variable is placed on the stack and then the stack pointer 
is decreased. Hence the stack loads as 


msgl_| (lowest address) 
offset of msg1 (next lower address) 
segment address of msgl (highest address) 


Following this loading of the stack a call to the DLL routine (dlink1) is made. 
The operating system automatically places a return address (4 bytes for a FAR call) 
on the stack in response to the call instruction. Figure 5.4 illustrates the called pro- 
cedure, dlinkl, contained in the module dlinkl.asm. The first instruction of the 
called procedure saves the old (current) value of bp and sp now points to this saved 
copy of bp. Recognizing that the stack pointer is decreased following each push, the 
following stack values appear on the local stack: 


caller’s bp (lowest address) 
caller’s ip 

caller’s cs 

msgl | 

offset of msg1 

segment address of msgl (highest address) 


In the routine dlink1 the next instruction transfers the value in sp (which is the 
saved copy of the old bp’s address) to bp. The routine pushes ds (which points to 
the dynl.asm data segment) and loads the DLL routines’s data segment address into 
ds. The program can now access structures of the form specified by stl, which 
appears in the new data segment. This access takes the form 


variable.field 


where the fields specified for st1 are m_len, m_offs, and m_seg. There are also three 
unnamed fields. Choosing variable equal to the address of the old bp, we can access 
the stack using the structure template. Hence the following values of interest can be 
retrieved by the DLL routine: 
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TITLE DLINK1 -- DLL routine for example #1 (dlinkl.asm) 


DESCRIPTION: This is the DLL routine for example #1. 


It is pre-loaded. 


-286C 
-sall 


tJ 
extrn VioWrtTTY: FAR 


i 
dgroup GROUP data_dlli 


’ 
data_dll1 SEGMENT PARA PUBLIC 'DATA' 
vio_hdl equ 0 


stl struc 

dw 

dw 

aw 

dw 

dw 

dw 

ENDS 
data_dll1l ENDS 


CODE1 SEGMENT PARA PUBLIC 'CODE' 
ASSUME CS:CODE1,DS:dgroup 
PUBLIC dlinkl 

alink1 PROC FAR 


push bp 

mov bp,sp 

push ds 

mov ax,data_dll1l 
mov ds,ax 


push [(bp].m_seg 
push [(bp].m_offs 
push [(bp].m_len 
push vio_hdl 


call FAR ptr VioWrtTTY 


pop ds 
pop bp 
ret 
dlinkl ENDP 
CODE1 ENDS 
END 


;Suppresses macro listings 


sAPI routine 


:video handle 


;parameter structure 
;caller's bp 
;caller's ip 
;caller's cs 
;message length 
smessage ptr offset 
;message ptr seg 


;caller's frame ptr 


.flocal stack 


scaller's ds 
sload new ds 


suse explicit parameter 
svalues because locations 
scome from local stack 


e 
’ 


;message seg address 
smessage offset address 
zlength message 

;video handle 


sd@irect API call 


; 
;restore caller's data seg 
;restore frame pointer 


Figure 5.4 The called procedure, dlinkl, for the example of Figure 5.3. 


{bp}.m_len — length of msgl 
[bp].m_offs -— the offset of msgl 


[bp].m_seg — the segment address of msgl 


In dlink1 these values are pushed on the stack as well as the video handle and a 


FAR call to 


ViowrtTTY 


is made. Note that macro version is not used and the API service directly accessed. 
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Execution of these instructions results in the message “Dynamic Link Preloaded 
Routine” appearing on the screen with a line feed and carriage return. 

The routine dlink1 is a member of the DLL, dyn11.dll module created by the 
first link discussed above. This routine, dlinkl.obj, was linked with a routine 
dyninit.obj. What is this routine? Each DLL must have an initialization routine. For 
dyn11.dll the initialization routine is dyninit.obj and this routine appears in Figure 
5.5. This initialization routine simply writes the message “DLL Initialized” to the 
screen and forces the operating system to initialize the DLL. To ensure that the ini- 
tialization routine executes first the DLL entry point to the module’s procedure, init 
is specified as a parameter in the END pseudo-op: END init. Following initialization 
the routine must return a value of 1, not 0, to the calling program. 


PAGE 40,132 
TITLE DYNINIT -- Initialization Routine for DLL-1 (dyninit.asm) 


° 
’ 


; DESCRIPTION: This routine is the initialization routine 
for the DLL dynil.dll. The routine merely prints a message. 
; 


-286c 
-sall ;Suppresses macro listings 


-xlist 
include sysmac.inc zinclude API services 
-list 


; 

dgroup GROUP init_data :defines automatic data seg 
; 

init_data SEGMENT PARA PUBLIC 'DATA' 


initOK equ 1 ;OK return code 

msg db 'DLL Initialized',ODH, OAH ;Initialization message 
msg_l equ $-msg ;message length 

vio_hdl equ 0 ;video handle 


init_data ENDS 

CINIT SEGMENT PARA PUBLIC 'CODE' 
ASSUME CS:CINIT,DS:dgroup 

init PROC FAR 


push bp ;save frame pointer 
@VioWrtTTY msg,msg_1,vio_hdl ;Write initialization msg 
mov ax, initOK 7OK return value 


£ , 

pop bp ;restore frame pointer 
ret 

ENDP 

ENDS 

END init ;DLL entry point 


Figure 5.5 The initialization routine for the DLL called by the program in 
Figure 5.3. 
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Finally, Figure 5.6 presents the module definition file. This file is associated 
with the library dyn11.lib. Hence all references to segments and routines must come 
from dlink1.asm and dyninit.asm. In this example these segments are preloaded, as 
specified in the definition file. Only dlink1 is exported because this is the only 
routine used by dyn1l.exe. Note that the presence of LIBRARY specifies that dyn11 
will be a DLL. 


LIBRARY 
PROTMODE 


DESCRIPTION ‘Example #1 DLL' 


SEGMENTS 


init_data CLASS 'DATA' PRELOAD 
CINIT PRELOAD 
data_dlll CLASS "DATA' PRELOAD 
CODE1 PRELOAD 


EXPORTS 
dalink1 


Figure 5.6 The module definition file, dynll.def. 


Example 2. For this example, a load-on-call execution was prescribed for the 
DLL routines exported to the application. All routines remain the same as in Ex- 
ample 1 except the definition file, named dyn11.def. This file appears in Figure 5.7. 


LIBRARY 
PROTMODE 
DESCRIPTION "Example #2 DLL' 


SEGMENTS 


init_data CLASS 'DATA' LOADONCALL 
CINIT LOADONCALL 
data_dlll CLASS 'DATA' LOADONCALL 
CODE1 LOADONCALL 


EXPORTS 
dalink1 


Figure 5.7 The module definition file, dyn22.def. 


It is important to note that the data segments (init_data, for the initialization routine, 
and data_dll1, for the DLL routine) in the DLL as well as the Code segments in the 
DLL are loaded as called based on the parameter LOADONCALL. 

The link and definition utilities are executed as follows: 
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link dyninit dlinkl, dyn22,,doscalls.lib,dyn22.def 
implib dyn22.lib dyn22.def 


link dynl.obj, dynl.exe,,doscalls.lib dyn22.1ib,, 


These commands produced an executable module, dynl.exe, which accessed the 
dynamic link library, dyn22.dll, and imported the routine dlink1 only when actually 
called in the program dyn1.exe. In the earlier example access was granted immedi- 
ately because of the preload condition. Execution of dynl.exe produces the same 
result as it did in Example 1, but the DLL input occurred at load time rather than 
when linking takes place. Note that the message to the screen still reads 


“DLL Initialized 
Dynamic Link Preloaded Routine” 


even though the load-on-call status exists. This is because we have changed only the 
definition file to check this DLL implementation. 


Example 3. In this example we illustrate an example of run-time dynamic 
linking based on the OS/2 API services. Following the lead set by the first two 
examples, the routines dyninit.asm and dlink1l.asm were used to make up the DLL. 
Figure 5.8 illustrates the main calling module, dyn2.asm. 

The routine dyn2.asm uses the API service @DosLoadModule to load the 
DLL (DYN33.DLL) and it returns a handle to the DLL. To access entry points 
within DYN33.DLL the API services macro @DosGetProcAddr is called and an ad- 
dress returned for the entry DLINK1. This address is returned in addr_proc. Next the 
message parameters are pushed on the stack so that they can be accessed by 
DLINK1. A call is made via the CALL instruction and this writes msgl1 to the 
screen. Following release of the DLL using @DosFreeModule, the program exit 
takes place. Note that the two ASCIIZ strings corresponding to the DLL and the 
entry point name have uppercase letters. This is because the assembler always uses 
uppercase and both the API functions in dyn2.asm are case sensitive. The CALL 
instruction is not case sensitive; hence the references to dlink1 in dynl.asm are 
unaffected by whether the reference is to dlinkl or DLLNK1. In dyn2.asm the 
references must be upper case. 

Figure 5.9 illustrates the DLL definition file for Example 3. There are few 
changes in this file (DYN33.DEF) from earlier .def files. These three examples 
constitute the three ways in which dynamic link libraries can be implemented under 
OS/2. The examples all employed assembly language for both the calling module 
and the routines appearing in the DLL. The link sequence for Example 3 is as 
follows: . 


link dyninit + dlinkl1,dyn33,,doscalls,dyn33.def 
implib dyn33.lib dyn33.def 


link dyn2,dyn2,,doscalls+dyn33,, 
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PAGE 40,132 

TITLE DYN2 - Main calling program example #3 (dyn2.asm) 

DESCRIPTION: This program calls dyn33.dll to demonstrate 
explicit load by application assembler dynamic link libraries. 
The main calling routine is DYN2. 


=e ~e “8 “Ee OS 


~286c 
-sall ;Suppresses macro lists 


-xlist 
include sysmac.inc ;API services 
-list 


s 
dgroup GROUP data ;defines automatic data seg 


’ § 

STACK SEGMENT PARA STACK 'STACK' :stack defined 
db 128 dup( 'STACK ‘) 

STACK ENDS 


data SEGMENT PARA PUBLIC 'DATA' 

; 

msg1 "Dynamic Link Run-Time Routine! ,0ODH, OAH 

msgi_1 $-msg1 

msg2 ‘Error on access DLL',0ODH, OAH 

msg2_1 $-msg2 

; 

action ;code to end thread 
result ;return code for error 
vio_hdl ;video handle 


obj_buf 64 dup(?) serror returm buffer 
obj_buf_len $-obj_buf ;length error buffer 
obj_buf_add obj_buf ;address buffer 
name_mod 'DYN33',0 ;module name 

hhandle 0 shandle to DLL module 
c 

name_proc "DLINK1',O . ;DLL procedure name 
addr_proc 0) 


a 
data ENDS 


e 

CSEG SEGMENT PARA PUBLIC 'CODE' 
ASSUME CS:CSEG,DS:dgroup 

DYN2 PROC FAR 


° 
’ 


@DosLoadModule obj_buf_add,obj_buf_len,name_mod, hhandle 
cmp ax,0 :check for error 
jne ERROR 

@DosBeep 4000,200 

@DosGetProcAddr hhandle,name_proc,addr_proc 

cmp ax,0 ;check for error 
jne ERROR 


° 
’ 


@DosBeep 1000,500 


push ds ;push message segment 
lea bx,msgl ;offset of message 
push bx ;save offset 

push msgi_1l ;message length 


call addr_proc DLL routine to print msg 


Figure 5.8 Run-time dynamic linked library calling module. 


Sec. 5.3 Optimizing the C Design Process 239 


@DosFreeModule hhandle 
cmp ax,0 ;check for error 
je EXIT 


@VioWrtTTY msg2,msg2_1,vio_hdl ;error message 


@DosExit action, result ;terminate all threads 
ENDP 

ENDS 

END DYN2 


Figure 5.8 (Concluded) 


LIBRARY dyn33 INITINSTANCE 
PROTMODE 

DATA NONSHARED 
DESCRIPTION ‘Example #3 DLL' 


SEGMENTS 


init_data CLASS 'DATA' LOADONCALL 
CINIT LOADONCALL 

data_d1ll CLASS "DATA' LOADONCALL 
CODE1 LOADONCALL 


HEAPSIZE 1024 


EXPORTS 
dalink1 


Figure 5.9 The module definition file, dyn33.def. 


It is possible to access a DLL in an additional fashion: through specification 
of IMPORTS entry points in a module definition file. By listing the library entry 
points to be imported in a definition file for the application, the application can 
import DLL routines. 


5.3 OPTIMIZING THE C DESIGN PROCESS 


Most modern textbooks address the topics of structured programming, modular code, 
and top-down design. These techniques have come to embody an organized ap- 
proach to program development which is repeatable in an optimal sense. This 
approach is predictable and meaningful in that programmers of differing back- 
grounds will approach algorithm development in the same fashion when these tools 
are used. In the following discussion we explore each of these topics, starting with 
top-down design because it represents the start of the design process. 
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5.3.1 Top-Down Design, Structured Programming, 
and Modular Code 


Top-down design is an informal strategy for starting with a global problem statement 
and then subdividing the development into smaller and smaller modules until each 
module accomplishes a singular task. Such a systematic approach to design leads to 
modular techniques that develop and link program elements together to solve the 
overall task. 

A convenient starting point for the top-down approach is to define the func- 
tional structure for the program under consideration. This functional structure has 
been reflected in the Structure Charts of earlier programming examples. These charts 
illustrate a hierarchy of importance for the components of the program. Structure 
Charts are established by associating with level 0 an overall functional statement of 
the programming problem. This occupies a single box at the top of the hierarchy. 
Next, the level 1 position categories associated with variable I/O and algorithm 
computation are indicated at a reasonably high level. Below this level, successive 
reduction of the problem into multiple smaller pieces occurs, with the relationships 
clearly defined. Through this process the program architecture is defined in terms of 
hierarchy. The Structure Chart does not, however, illustrate the dynamic interrela- 
tionship among modular components. Also, it does not illustrate at the module level 
the flow of execution for the program. To achieve this, the top-down design proc- 
ess needs an additional mechanism for describing program activity. This mechanism 
can take one of two forms: the flowchart or pseudo-code, which describes the pro- 
gram activity in natural-language syntax. In this book we employ flowcharts for de- 
scribing programs dynamically. (The reader can just as conveniently approach pro- 
gram design using pseudo-code, but it is generally less compact than flowcharts, 
hence our use of the latter technique.) 

In general, the procedure discussed here is a reasonable approach to program 
design. The structure chart reflects the high-level functionalism and the flowcharts 
illustrate the more detailed dynamics at the module level. Top-down design is infor- 
mal and thus most useful for small-scale design tasks. When faced with larger de- 
sign problems, the programmer must resort to additional techniques to supplement 
the guidance obtained from the top-down methodology. We will consider two addi- 
tional tools, as discussed earlier: modular programming and structured code. 

The reader will note by now that in programs appearing in this book, there is 
a tendency to relegate many of the tasks to smaller functions and modules. This 
suggests the notion of modular programming. Modular programming concepts have 
been established over a long period of time during which theoretical methods 
evolved for designing programs [3,4]. The principal requirement on smaller program 
units or modules is that they be independently testable and can be integrated to ac- 
complish the overall program objective. 

Modules are generally defined, in the context of C programming, in terms of 
one or more related functions. Each function should perform a single independent 
task and be self-contained, with one exit and entry point. This suggests a single 
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“thread” to program execution, which is the manner in which most modern comput- 
ers execute code. Module execution in the world of the CPU is sequential. With this 
architecture in mind, it becomes straightforward to accept the one entry and one exit 
feature associated with functions, at least theoretically. 

We discussed global variables as a mechanism for returning more than one 
value from a function. When is this likely to become most necessary? One situation 
is the generation of an array of similar values. Here a single function might be used 
to compute a time series, for example, and each computation would generate an 
array element in recursive fashion. Obviously, the function should be self-contained 
and all array values generated at once. Consider the following function: 


filter (N) 
int N; 
{ 
extern float y[]. x[]; /*x=time element*/ 
float b, c; 
int n;3 
y[0]=0; /*Initialize*/ 
b=.01; 
c=.001; 


for (n=l; n<=N; n++) 
y(nj=c*y[n—1]+b*x[{n]; 


} 


This low-pass filter generates a smoothing of the time series x[n]. The array y[n] is 
generated in its entirety with the simple one-statement for loop. It would be highly 
undesirable to fail to return the complete array from this function; hence the use of 
global variables is appropriate. This use does not detract from the modular nature of 
the function. Thus even though a module (or function) has one entry and one exit 
point, multiple values can be returned. 

Size is handled by accepting a general guideline that modules contain between 
10 and 100 lines of code. This is suggested as a rule of thumb and if, for example, 
the code were written in APL, 100 lines would be very tiresome to debug. For C, 
however, the guideline seems appropriate, as evidenced by the modules in this book. 
A more rigorous enforcement of size must resort to quantitative measures such as 
complexity and complexity metrics. Consider the metric [5] 


N = N1 + N2 (5.1) 
where 


N1 = total number of operators in a module 
N2 = total number of operands in a module 


Returning to the function filter, the following counts apply: 
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OPERATOR COUNT OPERAND COUNT 
= 6 y[0] 2 
for 1 b 3 
< 1 Cc 3 
++ 1 0 1 
‘ 2 yl 3 
x[] 2 
n 7 
__ N _3 (variable) 
11 24 


Here N is 35 [from Equation (5.1)]. What does this mean? To interpret N, a body 
of statistical data must evolve based on complex interactions between programmers 
and code. It is clear from this example that N = 35 is a reasonably simple program. 
In reference 6, a similar example with N = 28 is illustrated. Again, this metric value 
indicates a relatively small and understandable module. 


The programmer is unlikely to apply a complexity metric during program de- 


velopment. It is, nonetheless, useful to allow complexity to guide program develop- 
ment, particularly when modules begin to approach a high level of difficulty (for the 
programmer developing the code). Let us summarize some general guidelines on 
module development in C: 


1. 
2. 


des 


e 


Restrict modules to between 10 and 100 lines of code. 


Within the module concept, allow one entry and one exit (exception handling 
can call for multiple exits, but this is an abortive condition and the error state 
should be flagged before the exit). 


. Arrays should be treated globally. 


Modules returning a single value should do so formally with return(). 


. Modules returning multiple but small numbers of variables should do so with 


pointers (pointers are complex, so the trade-off here is how many pointers are 
involved). 


. Modules returning large numbers of variables, other than arrays, should be 


rewritten. 


. Modules returning an intermediate number of variables can do so with global 


declarations. 


. A module should perform one self-contained task. 
. Allow for exceptions to these guidelines when the code can be made easier to 


understand and it is not time-critical. 
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TABLE A.2. MACRO ASSEMBLER INSTRUCTIONS (8086 CONVENTION) 


Instruction 


Arithmetic 
ADC dest,src 


ADD dest,src 
DIV src 


IDIV src 


IMUL src 


MUL src 
SBB dest,src 


SUB dest,src 
Logical 
AND dest,src 


NEG dest 
NOT dest 
OR dest,src 


TEST dest,src 


XOR dest,src 


Move 
MOV dest,src 


MOVS dest-str, 
src-str 


Load 
LODS src-str 


Purpose 


Add with carry 


Addition 
Unsigned divide 


Signed integer 
division 

Signed integer 
multiply 

Unsigned multiply 


Subtract with bor- 
row 


Subtract 


Logical AND 


Two’s complement 

Logical NOT 

Logical inclusive 
OR 

Logical compare 


Exclusive OR 


Move 


Move byte or word 
string 


Load byte or word 
string 


Comments 


Performs an addition of the two ope- 
rands and adds one if CF is set. 


Adds the two operands. 

Divides the numerand (AL and AH for 
byte division and AX and DX for 
word division) by src. The result 
is returned in AL (byte) or AX 
(word). 

Signed division using the registers of 
DIV. 


Multiplies AL or AX times src. 


Same as IMUL. 


Subtracts the two operands and sub- 
tracts one if CF is set. 


Subtracts the two operands. 


Performs the bit conjunction of the two 
operands: the result is zero except 
when both bits are set. 


Forms the two’s complement of dest. 
Inverts dest bit by bit. 


Performs the bit logical inclusive dis- 
junction of the two operands: returns 
a one except when both bits are zero. 


Performs the bit conjunction of the two 
operands with only the flags affected. 


Performs the bit logical exclusive dis- 
junction of the two operands: returns 
a one when one operand is zero. 


Moves: 
1. To memory from AX (AL) 
2. To AX (AL) from memory 
3. To seg-reg from memory/reg 
4. To reg from seg-reg 
5. To reg from reg 
To reg from memory 
To memory from reg 
6. To reg from immediate 
7. To memory from immediate 
Transfers a byte or word string from 
src, addressed by SI, to dest, ad- 
dressed by DI. 


Transfers a byte (word) from src, ad- 
dressed by SI, to AL (AX) and ad- 
justs SI. 
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easier to implement in assembler since the API in OS/2 is presented as a generic as- 
sembler interface. C provides such an interface but is sophisticated and relies on the 
use of special macro libraries (see Appendix C) to set up the API function calls. 
With these thoughts in mind, let us briefly summarize the IBM Macro Assem- 
bler/2. We will not attempt to illustrate examples of the language; the early chapters 
accomplish that. In this appendix we merely present the assembler constructs in 
tabular form based on reference 3. Table A.1 presents the addressing modes for the 
language. There are seven forms of addressing within the Macro Assembler. Table 
A.2 contains brief descriptions for the basic instruction set common to the Intel 8086 


TABLE A.1| MACRO ASSEMBLER ADDDRESING MODES 


Mode Comment 
Immediate A byte or word constant in the source operand is loaded into a 
register operand. Example: mov ax, 18. 
Register Register destination operands are loaded from register source ope- 
rands. Example: mov ds,ax. 
Direct A register destination operand is loaded with the value of a location 


specified by its offset added to DS. Example: mov ax,dddw, where 
dddw is a variable in the data segment (addressed by DS). 


Register indirect The effective address (segment offset) is contained in BX, BP, SI, 
or DI, and this is used to load a register. Example: 


mov bx» OFFSET dddw 
mov ax»Cbx J 


Here the brackets indicate bx contains an address. 


Base relative The effective address for the source is obtained by adding a displace- 
ment to BX or BP, which are assumed to contain an offset, Example: 


mov bre +OFFSET dddw 
mov ax+Cbre+a4] 


Direct indexed Here the effective source address is the sum of an index register 
(SI or DI) and an offset. Example: 


mov s1+4 
mov axr+dddw [sil 


This loads ax with the same value as loaded in the base relative 
example. 
Base indexed Typically, the effective source address is the sum of a base register 
(BX or BP), an index register (SI or DI), and a displacement. 
Example: 


mov bx sOF FSET dddw 
mov 6194 
mov ax+CbxJ][Csit2] 


Appendices 


A IBM Macro 
Assembler/2 


In this appendix we present the IBM Macro Assembler/2, which can be used to 
program the assembler under both DOS and OS/2 [1, 2]. In the early chapters all 
programming was accomplished in assembly language. A major consideration, 
however, is how desirable is this choice of language for the IBM microcomputer en- 
vironment? The answer lies in how the programmer intends to use the assembly lan- 
guage. Basically, assembler is very programming intensive and serves best when 
access of the system hardware is important. For the OS/2 Kernel service functions 
this is particularly important when acquiring or writing to the display, the video 
services (Vio), or the DOS functions (Dos) within the API. In addition to access of 
the system hardware, another associated requirement should be mentioned: rapid 
access of the hardware. The assembler is ideally suited for this requirement but has 
the added stipulation that the programmer must be prepared to devote considerable 
effort to writing very low-level code. 

In this book an alternative language, the C programming language, is consid- 
ered. C is more ideally suited for programming applications that require higher-level 
functions to accomplish tasks. Typical examples of these functions are sine and 
cosine, other hyperbolic and trigonometric functions, and a multitude of mathemati- 
cal and statistical special-purpose functions. These can all be built up from assem- 
bly language programs by the user, but it is usually more desirable to access these 
functions through a high-level language, using the assembler-constructed libraries 
within the language. The general experience is, however, that the API calls are 
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5.12 Why are all lines appearing in Figures 5.19 through 5.23 not removed using the cri- 
teria that a negative direction to the facet normal constitutes a hidden line? 


5.13 Show that the limit of Equation (5.13) is A* when (x, y) = (0, 0). 
5.14 In the surface plotting program appearing in Figure 5.14, the disk read function, 
xarray_diskrd(), is called prior to setting the CGA screen mode. Why? 


5.15 In Figure 5.17 ,how would the function threeD_facets() change (aside from removal 
of the define and include statement associated with OS/2) if this routine were to exe- 
cute in a normal Real Mode program? 
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PROBLEMS 


If a routine is self-contained within a task and called very infrequently, what OS/2 
technique could be used to conserve storage? 


What sequence of steps differentiates a DLL from another executable module? 
In Figure 5.2, what is the parameter on the stack at BP+2? 
How does one differentiate a DLL module from another source code module? 


Define the difference between IMPORTS and EXPORTS as appearing in the module 
definition file. 

What key API services are required for run-time DLL loading which are not required 
for load-time linking? Structurally, why are these API services needed? 

If you wished to achieve an understanding of the relationships between program 
components, would you choose a Structure Chart or a flowchart? Explain. 

What is the dominant characteristic of a C function? What are the implications of 
this characteristic for program structure? 

In C program code, when is it appropriate to use globally defined variables? Why 
are these variables generally considered undesirable to program understanding? 


5.10 Why is the include file “pmwin.h” not available as part of OS/2 Version 1.0? 


5.11 


In defining the three-dimensional surface, the grid of points is defined in the x-y 
plane and facets established by connecting cyclically the projected points defined by 
the surface itself. In plotting the resulting surface, the points are collapsed along the 
x-axis. Why is this necessary? 
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5.6 SUMMARY 


This chapter has provided an examination of additional basic OS/2 features within 
the core API and has reinforced programming techniques within the C language, the 
primary language of choice for programming the Presentation Manager as well as 
more complex activities under OS/2. We began with a look at mixed-language pro- 
gramming in the context of C and assembler. Next, dynamic linked libraries were 
investigated from the viewpoint of assembly language, where they are more clearly 
understood. The use of load-time DLLs is recommended when memory allocation is 
to be optimized and a set of routines is to be called on a frequent basis. Load-time 
dynamic linking has the advantage that the calling routine does not need to ascer- 
tain the location of the module at loading. Run-time dynamic linking is recom- 
mended for those applications where memory allocation is dynamic and at a pre- 
mium and the routines to be accessed are done so infrequently. This technique 
requires access through API service calls. 

The C design process was examined from the viewpoint of top-down design, 
structured programming, and modular code. Recommendations were provided regard- 
ing module size and implementation. A typical template for C design was presented 
and the difficult issues of style and form touched upon. Style is such a crucial factor 

_in the development of maintainable code that it is very surprising how often it is 
overlooked. Similarly, form can mean the difference between code that runs, and 
code that purports to accomplish the job but is so cumbersome and slow that it fails 
to achieve its objectives within a reasonable length of time. 

All the API services return values that depend on the outcome of the call. The 
question of whether or not a program should monitor those outcomes, once the 
original debugging is complete, was left to the reader. Frequently, in the interest of 
brevity, the full API return checking has been suppressed in this book unless a 
hardware failure can result, such as the inability to access a disk. 

A reexamination of the basic API core services was referenced: the Kbd, Mou, 
Vio, and Dos services. These are the Version 1.0 services and have since been 
added to by the presence of the PM functions, although these PM services are not 
treated in this book. Finally, a C application was developed. This application con- 
sisted of the plotting of a three-dimensional surface in the CGA mode of the OS/2 
command screen mode. The purpose of the presentation was to illustrate the man- 
ner in which moderately large-scale programs would be interfaced to OS/2 in the 
normal operational environment, with a particular emphasis on the techniques out- 
lined earlier in the chapter, such as modular code development. 
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uwdot (col, row,MM1) ; /* erase dot */ 
} 


} 
else 


{ 
col = (int) (x1); 
if(yl > y2) 


{ 
(int) (y1) ;row++) 


for (row=(int) (y2)+l;row <= 
/* erase dot */ 


uwdot (col, row, MM1) ; 


} 
else 


{ 
for (row=(int) (y1)+1l;row <= (int) (y2) ;rowt++) 
uwdot (col, row, MM1) ; /* erase dot */ 


} 


Figure 5.18 (Concluded) 
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if(xl == x2) 

m = 1000.; zero divide */ 
else 

m= (y2~-yl)/(x2-x1) ; normal slope */ 
if( x2 > x1) 


{ 
for(col = (int) (x1)+1l;col <= (int) (x2) ;colt++) 
{ 
row =(int) (yl + m*(col - x1)); /* line equation */ 
wdot (col, row, MM1) ; /* write dot */ 
} 


else 


{ 
if(x2 < x1) 


{ 
for(col =(int) (x2)+1;col <= (int) (x1) ;col++) 


{ 

row=(int) (y2 + m*(col - x2)); 

wdot (col, row,MM1) ; /* write dot */ 
} 


) 
else 


{ 
col = (int) (x1); /* verticle line */ 
if(yl > y2) 


for (row=(int) (y2)+l;row <= (int) (yl) ;rowt++) 
waot (col, row, MM1) ; 
) 
else 


{ 

for (row=(int) (yl1)+l;row <= (int) (y2) ;row++) 
wdot (col, row, MM1) ; 

} 


} 


upltpt (x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 


{ 

float m;  f* slope */ 
int row; 

int col; 


if(xl == x2) /* zero divide */ 
m = 1000.; 
else 
m = (y2-yl)/(x2-x1) ; /* normal slope */ 
if(x2 > x1) 


{ 

for(col = (int) (x1) ;col <= (int) (x2) ;colt++) 
{ 
row = (int) (yl + m*(col - x1))? line segment */ 
uwdot (col, row,MM1) ; erase dot */ 
} 

) 

else 

{ 

if(x2 < x1) 
{ 
for(col = (int) (x2)+1;col <= (int) (x1) 7col++) 


{ 
row=(int) (y2 + m*(col -x2)); 


Figure 5.18 (Continued) 
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/* Graph routines Protected Mode--gphrout.c */ 


#define INCL_BASE 
#include <os2.h> 


bboxx (xb, xe, yb, ye, MM1) 
UINT xb,xe,yb,ye; 


SEL MM1; 
{ 
lineh(yb,xb,xe,MM1) ; /* top line */ 
lineh(ye,xb,xe,MM1) ; /* bottom line */ 
linev (xb, yb, ye,MM1) ; /* right line */ 
linev(xe,yb,ye,MM1) ; /* left line */ 
} 
lineh(y,x1,x2,MM1) 
UINT y,x1,X2; 
SEL MM1; 
{ 
UINT n; 
for(n = xlj;n <= x2;nt+) 
wdot(n,y,MM1) ; /7* hor line */ 
} 
linev(x,y1,y2,MM1) 
UINT x,y1,y2? 
SEL MM1; 
{ 
UINT n; 
for(n = ylin <= y2;n++) 
wdot (x,n,MM1) ; /* vertical line */ 


} 
wdot (x, y,MM1) 


UINT x,y; 
SEL MM1; /* x=col,y=row */ 
{ 
PCHAR ptr; 
UINT DM = 0x0000; 
CHAR MASK1 = 0x01; /*® set dot */ 
if(y & 0x01) 
DM = 0x2000; /* even buffer */ 
ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 2)))? /* dot location */ 
*ptr =(*ptr | (MASK1 << (2*(3 - x % 4)))); /* “OR" dot */ 
) 
uwdot (x,y,MM1) 
UINT x,y; 
SEL MM1; 
{ 
PCHAR ptr; 
UINT DM = 0x0000; . 
CHAR MASK1 = 0x00; /* clear dot */ 
é 
if(y & 0x01) 
DM = 0x2000; /* even buffer */ 
ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 2))); /* dot location */ 
*ptr = (MASK1 << (2%*(3 - x % 4)))? /* write undot */ 


pltpt(x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 


{ 
float m; /* slope */ 
int row; : 

int col; 


Figure 5.18 The file gphrout.c, containing the expanded line plot routines (and 
the line unplot routines). 
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/* Function to plot 3D facets: coordinates for CGA -- facet3d.c*/ 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


threeD_facets (m1, MM1) 
int ml; /* index */ 
SEL MM1; 


extern int count; 

extern float xarray[],x,y,z,scaley = 125.,scalez = 75.; 
float 21,22,y1,y2; 

int n,nc; 

float z_start = 25.,y_ start = 25.,z_mid = 75.,y mid = 125.; 
float dy1,dy2,daz1,daz2,xa[5],ya[(5],za[5]; 


nce = 3*count; /* next y~value */ 
xa[1] xarray[ml]; /* Ast y-value grid */ 
ya{l]j xarray(m1+1); 

za({1j xarray[m1+2); 

xa(2] xarray(m1+3); 

ya(2] xarray(m1+4]; 

za[2] xarray([(m1+5]); 


xa[3] 
ya[3] 
za[3] 
xa[4j 
ya[4] 
za(4] 


xarray(ml+nc+3]; 2nd y~value grid */ 
xarray ([m1+nct+4); 

xarray ([m1l+nc+5]; 

xarray(mitnc]; 

xarray [m1+nc+1); 

xarray (m1+nct2]; 


dyl ya[1]; ck rotation 
dy2 ya[2]; 
dz1 za({1); 
az2 za(2]? 
if((dy1*dz2 - dz1*dy2) > 0) 
{ 
for(n = 1l;n <= 4;n++) /* scale facet 
{ 
za(n) 
ya[(n] 


= z_start + (z_mid - za(n]*scalez) ; 
= y_ start + (y_mid + ya[n]*scaley) ; 


1l3n <= 3;n++) /*® plot 3 of 4 


ya(n)j; 
ya[(n+1]; 
za(nj; 
za(nt+1]; 


pltpt(yl,y2,21,22,MM1); collapsed y-z */ 


ya(4]; 

ya[{l1]j; 

za[4]? 

za[1j; 

pltpt(y1,y2,21,22,MM1) ; /* 4th segment */ 
} 


Figure 5.17 The file facet3d.c, used to generate the individual surface facets. 


Sec. 5.5 Advanced C Example: A Three-Dimensional Surface 261 


/* Function to scale xarray data */ 
#include <stdio.h> 


scale() 
{ 
extern int ncount,mcount; 
extern float xarray[],scalex,scaley,scalez; 
int n,m,mil; 
float max_x = -1.e14,max_y = -1.e14,max_z 
float min_x = 1.e14,min_y = 1.e14,min_z = 


ml = 1; 
for(n = 1;n ncount ;n++) 


<= mcount;mt++) 
/* max/min determine */ 
xarray([m1}) 
xarray [ml]; 
xarray[{mi]) 
xarray[ml]; 
xarray[ml1+1]}) 
xarray[(ml1+1); 
xarray(m1+1]) 
xarray[(ml1+1]; 
xarray(ml1+2]) 
xarray (m1+2]; 
xarray(m1+2)); 
= xarray([(m1+2]; 
ml = ml + 3; /* next point set */ 
} 


< 
> 
< 
> 
< 
> 


} 
/* scale [(-1,1] */ 
scalex 2./(max_x - min_x); 
scaley = 2./(max_y - min_y); 
scalez 2./(max_z - min_z); 
m1 = 1; 
for(n = 1l;n <= ncount;nt++) 
{ 
for(m = 1;m <= mcount;m++) 
/* normalize [{1,-1] */ 
xarray[(ml] = -1. + scalex*(xarray[m1] - min_x); 
xarray(m1+1] = -1. + scaley*(xarray[ml+1] - min_y); 
xarray[m1+2] = -1. + scalez*(xarray(ml1+2] - min_z); 


ml + 3; 


Figure 5.16 The file xscale.c, used for scaling the array between (-1,+1) along 
all three axes. 


tively, this tilts the viewing angle upward so that the observer is looking down at an 
angle toward the image. Figures 5.20 through 5.22 maintain a and y at zero but 
change £ to span 1.0, 1.2, and 1.4 radians, respectively. This progressively tilts the 
image toward the reader, as illustrated. Figure 5.23 presents the figure for a = y = 
O and 6 = 1.0 with N = 12 instead of N = 7 [see Equation (5.13)]. 
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VioGetPhysBuf( (struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll) ; 


MM = PVBPrtl.asel([(0]; /* selector */ 


/* CGA clear */ 


vioScrUnLock(vio_hdl1) ; /* unlock screen */ 


Figure 5.14 (Concluded) 


/* Function to read xarray from disk */ 
#include <stdio.h> 


xarray_diskrd() 


extern float xarray[]; 
int n,check, counter; 
FILE *infile; 

char FN2[(81]; 


printf("Input read database filename \n"); 
gets (FN2) ; 
gets (FN2) ; 


if((infile = fopen(FN2,"r")) == NULL) 
{ 


printf("Input file failure"); 
exit(1); 


fscanf(infile,"%d \n", &counter) ; 
for(n = 1;n <= counter;n++) 
fscanf(infile,"%f \n",&xarray(n]) ; 
if((check = fclose(infile)) != 0) 
{ 


printf("Error on input file close") ; 
exit(1); 


return(counter) ; 


} 


The file xadiskr.c, for reading the disk file input to the surface 
plotting program. 


\ 


and if the facet is to be plotted, further scaling from [—1.,1.] to screen coordinates 
is implemented. Here only the y-z plane is considered (the x-axis is collapsed). 


Figure 5.18 contains the file gphrout.c used as a basis for the library 


cgraph.lib. These routines are called to access the screen buffer. Figure 5.19 illus- 
trates the output with a = y = 0 (no rotation about the x and z axes). In this figure 
B= 0.8, which is a counterclockwise rotation of 0.8 radian about the y-axis. Effec- 
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) 


C1lrCGA (MMM) 
SEL MMM; 
{ 
INT n; 
INT N1 Ox1F3F; end odd buffer */ 
INT DM 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= Ni1;n++) 


ptr = MAKEP(MMM,n); odd far pointer */ 
*ptr = 0; clear odd buffer */ 


} 
for(n = O7;n <= N1;n++) 


{ 

ptr = MAKEP(MMM, DM+n) ; even far pointer */ 
*ptr = 0; clear even buffer */ 
} 


/* Function to read xarray from disk */ 
#include <stdio.h> 
xarray_diskrd() 


extern float xarray[]; 
int n,check, counter; 
FILE *infile; 

char FN2[(81]; 


printf("Input read database filename \n"); 
gets (FN2); 
gets (FN2); 


if((infile = fopen(FN2,"r")) == NULL) 
{ 
printf("Input file failure") ; 
exit(1); 


fscanf(infile,"%d \n", &counter) ; 
for(n = 1;n <= counter;n++) 
fscanf(infile,"%f \n",&xarray[n)); 
if((check = fclose(infile)) != 0) 
{ 
printf("Error on input file close"); 
exit(1); 


return (counter) ; 
) 


/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *)&STDm) ,vio_hdl); 


DosExit (action,error_code) ; 


} 


cclsCGA(vio_hdl11) 
SHANDLE vio_hdl1i; 
{ 

SEL MM; 

UINT waitl = 1; 

struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 


PVBPrti.pBuf = (BYTE far *) (0xB8000) ; /* phys buf start */ 
PVBPrti.cb = 0x4000; /* buffer length */ 


VioScrLock(wait1, (char far *)dstat,vio_hdll); /* lock screen */ 
. /* physical buffer */ 


Figure $.14 (Continued) 


258 


* #N 
* 


Additional OS/2 Considerations Chap. 5 


lkbd_buf.cb = 80; /* buffer size */ 


lane se Se ees sit ee rr kel */ 
printf("Input ncount\n") ; /* x-axis count */ 
scanf ("%d", &ncount) ; 
Printf("\n Square array: ncount=mcount\n") ; 
mcount=ncount ; /* y-xais count */ 
count=ncount; /* grid shift */ 
/* Input rotations */ 
printf ("Input x-rotation (rad) \n") ; /* x~rotation */ 
scanf ("tf", &alphaO) ; 
printf("Input y-rotation (rad) \n"); /* yrrotation */ 
scanf ("%f", &beta0) ; 
printf("Input z-rotation (rad)\n"); /* z-rotation */ 
scanf ("tf", &gamma0) ; 
rot_mat(alpha0,beta0,gamma0) ; /* loads global a[] */ 
N = xarray_diskrd(); /* @Aisk values */ 
ml = 13 /* 1st facet group */ 
for(n = lin <= ncount;n++) 
{ 
for(m = 1;m <= mcount;m+t) 
{ 
x = xarray(ml]j; /* x-input rotation */ 
y = xarray[mi1+1]j; /* y-input rotation */ 
2 = xarray(m1+2]; /* z-input rotation */ 
rot_point(); /* rotate (x,y,2) */ 
xarray[(m1] = x; /* reload x */ 
xarray(ml1+1) = y? /*® reload y */ 
xarray[ml+2]} = 2? /* reload z */ 
ml = ml + 3; /* inc index 3 */ 
} 
} 
Graphics Screen Access 
Seca eeewoe cm a cn i pt il a esa meri mo */ 
scale(); /* X,y,2Z-> [1,71] */ 


/*.set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *)&CGAm) ,vio_hdl) ; 


cclsCGA(vio_hdl) ; /* clear CGA screen */ 
VioScrLock(wait2,(char far *)dstat1,vio_hdl); /* lock screen */ 


/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *)&PVBPrt2,vio_hdl); 


MM1 = PVBPrt2.asel[0]; /* selector */ 
ml = 1; ; 
nm_count = 3*ncount*mcount - (ncount*3 + 6); /* adjust limit */ 


for(n = 1;n <= ncount;n++) 
{ 
for(m = 1l;m <= mcount;m+t+) 


if(ml < nm_count) /* check facet count */ 
threeD_facets(m1,MM1) ; /* plot facets */ 
ml = ml + 3; /* increment index */ 
} 
} 
prtscr (MM1) ; /* PrtSc routine */ 
VioScrUnLock (vio_hdl) ; : 7* unlock screen */ 


/* hesitate screen */ 
KbdStringiIn( (char far *)kbd_buf, 
((struct _STRINGINBUF far *) &lkbd_buf), 
wait, kbd_hdl); 


Figure 5.14 (Continued) 
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This routine sets & clears CGA mode with screen clear--mmain3d.c 


The generalized nomenclature is used. 
A 3D (sin(u)/u)**2 is plotted. 
The routine calls gphrout.c graphics functions. */ 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


UINT action = 0; 
UINT error_code = 0; 
UINT wait = 1; 


CHAR dstat(1]; 
CHAR dstat1[{1]; 


float xarray[3072],scalex,scaley,scalez,x,y,z,a[10]; 
int ncount,mcount, count; 


col1[320]}; 

MM[4] = (0x40,0x10,0x04,0x01 

w{8] = ({128,64,32,16,8,4,2,1 
s[4); 

shift1[4] = (6,4,2,0}; 
in_buffer1[4] {0x1B,0x4B,64,1); 
in_buffer2[{2] {OxOD, Ox0A}; 
in_buffer3(3] {0x1B,0x41,8)}; 
in_buffer4[2] {0x1B,0x32}; 
dev_name({5] = {'L','P','T','1', 


extern prtscr(); 


SHANDLE vio_hdl = 
SHANDLE kbd_hdl = 
UINT wait2 = 1,nnn; 
UINT xb = 75,xe = 150,yb = 25,ye = 175; 
SEL MM1; 

int n,m,m1,N,nm_count; 

float alphaO,beta0,gamma0; 


0; 
0; 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 
struct _VIOMODEINFO STDm; 


PVBPrt2.pBuf = (BYTE far *) (0xB8000); 
PVBPrt2.cb = 0x4000; 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 
CGAm.col = 40; 
CGAm.row = 25; 
CGAm.hres = 320; 
CGAm.vres = 200; 


STDm.cb = 12; 
STDm.fbType = 1; 
STDm.color = 4; 
STDm.col = 80; 
STDm.row = 25; 
STDm.hres = 720; 
STDm.vres = 400; 


Figure 5.14 The program mmain3d.c, which is the main 
plotting and printing the three-dimensional surface. 


Conditional load */ 
OS2 includes */ 


keyboard buf len */ 
keyboard buffer */ 


end thread */ 
result code */ 
reserved word */ 


lock status */ 
lock status */ 


needed globals */ 
x-y count max */ 


*/ 
raster line array */ 
byte mask */ 
gross weight */ 
dummy */ 
byte pos. shift */ 
location byte */ 
c.r & 1.f. */ 
escape sequence */ 
line spacing */ 


PrtScr routine */ 


video handle */ 
keyboard handle */ 
reserved */ 

box points */ 
selector */ 

plot variables */ 


‘direction cosines */ 


physical buffer */ 
CGA structure */ 
80 x 25 struct */ 


buffer start */ 
buffer size */ 


struct length */ 
CGA mode */ 

CGA color */ 
text columns */ 
text rows */ 

CGA hor res */ 
CGA vert res */ 


struct length */ 
80 x 25 mode */ 
STD color */ 
text columns */ 
text rows */ 

STD hor res */ 


‘STD vert res */ 


calling program for 
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/* Function to write xarray to disk */ 


#include <stdio.h> 


xarray_diskwt (NCOUNT) 
int NCOUNT; /* Number points */ 
{ 
int n,check; 
FILE *outfile; 
char FN1[81]; 
extern float xarray[]; 


printf("Input database filename\n") ; 
gets(FN1); 
gets (FN1); 


if((outfile = fopen(FN1,"w")) == NULL) 
{ 
printf("Output file failure "); 
exit(1); 


} 
fprintf(outfile,"%d \n",NCOUNT) ; 
for(n = 1;n <= NCOUNT;n++) 
fprintf(outfile,"%f \n",xarray([n]}) ; 
if((check = fclose(outfile)) != 0) 
{ 
printf("Error on output file close") ; 
exit(1); 
} 


Figure 5.12 The file xadiskw.c, which generates a Protected Mode disk write 
using reentrant library routines. 


mnain3d.obj: mmain3d.c 
cl -c -Zi mmain3d.c 


facet3d.obj: facet3d.c 
cl -c -Zi facet3d.c 


xscale.obj: xscale.c 
cl -c -Zi xscale.c 


rotmat.obj: rotmat.c 
cl -c -Zi rotmat.c 


rotpt.obj: rotpt.c 
cl -c -Zi rotpt.c 


xadiskr.obj: xadiskr.c 
cl -c -Zi xadiskr.c 


pprtscr.obj: pprtscr.c 
cl -c -Zi pprtscr.c 


mnain3d.exe: mmain3d.obj xscale.obj facet3d.obj pprtscr.obj\ 
rotmat.obj rotpt.obj xadiskr.obj cgraph.lib 
link /CO mmain3d+xscale+facet3d+rotmat+rotpt+pprtscr+\ 
xadiskr,,,cgraph,, 


Figure 5.13 The MAKE file for the program that plots a three-dimensional 
surface based on an input data file. 
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/* generate 3d surface */ 

#include <math.h> 

float xarray[2000],x[500],y[{500],z[500]; 
main() 


int n,m,ncount = 21,mcount = 21,m1,m2,N,NN; 
float A= 10., error = 1.e-5; 
double PI = 3.141592654,u,v? 


printf("Input interval divider\n") ; 
scanf ("%d", &NN) ; 


m2 = 1; 
ml = 1; 
for(n = 1l;n <= ncount;n++) 


for(m = 13m <= mcount;m++) 
{ 
x(m2] = (float) (m — mcount + 10); 
y(m2) = (float) (n - ncount + 10); 
u (double) (x{m2]); 
Vv (double) (y[{m2]}) ; 
u (double) ((PI/NN) *sqrt(u*u + v*v))?; 


if((u < error) && (u > -error)) 


z(m2] = A*(sin(u)/u) ; 


z(m2] = z[m2]*z[m2]); 
xarray[ml] = x(m2]; 
xarray(ml1+1] = y[m2]; 
xarray(m1+2] = z{m2); 
m2++; 
ml = ml + 3; 
} 
} 
N = ml-1; 
xarray_diskwt(N) ; 


Figure 5.11 The program gen3d.c, which generates the surface data file. 


trates the disk write function. Figure 5.13 contains the MAKE file for the program 
that plots the three-dimensional surface. 

Figure 5.14 presents a main calling function for the program that plots the 
three-dimensional surface input using xarray_diskrd(), which is contained in Figure 
5.15. The function threeD_graph() reads rotation angles for locating the observer and 
rotates the input points. These functions, rotmat() and rotpt(), have been mentioned 
previously. Next, the data is scaled using scale(), which appears in Figure 5.16. The 
function scale() simply ensures that all x, y, and z values lie within the interval 
([—1.,1.]. 

After scaling the data, threeD_graph() clears the screen, sets CGA display 
mode, and plots the facets using threeD_facet(). This function appears in Figure 
5.17. The routine threeD_facet() first loads the arrays xa[], ya[], and za[] with each 
of the four vertex points on the facet. A check for a hidden-line condition is made, 
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where the first row consists of Cartesian unit vectors. Since it is the x-axis term we 
are interested in, we examine 


1, = MMiny — 2M iny (5.10) 
Here 
/N “N SN 
m=m,i+m, j+m,k (5.11) 
If 
n, <0 (5.12) 


the facet contains hidden lines. 


A Simple Mathematical Example 


It is useful to create a simple example to illustrate a three-dimensional surface. 


Consider the function 
sin?[ (st /N ya x? + y? ] 
[(x IN? +y 


This function has the familiar (sin x/x)* behavior. We note that in the limit (x, y) 
= (0, 0) the result is 


z= A? (5.13) 


ZA (5.14) 
It is useful to generate values for x and y in the range [—10.,10.] with N = an input 


value that is a measure of the range of z. 
Figure 5.10 illustrates the MAKE file for a program gen3d.c, which creates 


gen3d.obj: gen3d.c 
cl -c -Zi gen3d.c 


xadiskw.obj: xadiskw.c 
cl -c -Zi xadiskw.c 


gen3d.exe: gen3d.obj xadiskw.obj 
link gen3d.obj+xadiskw.obj,,,, 


Figure 5.10 The MAKE file for the program 
that writes the data file for a three-dimensional 
(sin x /x)? surface. 


this surface data file. Figure 5.11 illustrates a main calling program that generates 
these values and writes them to disk. Initially, the total number of values (x, y, z) for 
each point on an x-y grid spaced at unity intervals in the range above, is written to 
disk followed by the points themselves in x, y, z order. This is an array and is 
defined as specified above. It is the array xarray[] in Figure 5.11. Figure 5.12 illus- 


Sec. 5.5 Advanced C Example: A Three-Dimensional Surface 253 


Connecting these points cyclically yields the surface facet. When collapsed along the 
x-axis we have the final points 


1: (O, Y,»f(%,> Yn) 

2: (0, y, m+)? f x, ? me), 
3: (0, Ynev? Caer Yn) 
4: (0, Yn? Cae ) 


If these points are plotted with the y-axis corresponding to column values and 
the z-axis corresponding to row values, a surface representation will be displayed 
with facets outlined. 

It is important to recognize that the surface described above will display all 
lines appearing in the facets. This includes “hidden lines,” which are those lines 
appearing in facets whose view would normally be obstructed. This obstruction re- 
sults from the fact that other facets are located in front of the facet in question when 
viewed in the chosen direction. 

To avoid illustrating hidden lines, it is useful to delete plotting of facets con- 
taining these lines. Although there are several ways to eliminate these hidden line 
facets, a very simple procedure is to create a vector normal to the facet and ignore 
the facet if this vector has a negative component pointing into the screen. Since the 
x-axis is normal to the screen, this implies that a negative, x-component of this 
normal vector would denote a facet with hidden lines. 

We can create this normal vector from any three points in the surface. Suppose 
that we have the vertices defined by vectors from the origin: 


P, = > Vp 2,) 
P, = A» Vy» 2,) (5.6) 
P, = (X55 Y3» Z,) 


and cyclically define line segments 


m, = (P,- P,) 
m,= (P,- P,) (5.7) 
m, = (P,— P,) 
Then a normal to the surface subtended by these three line segments is given by 
n=m,xm,, (i= 1, 2, 3) (5.8) 


In this equation i is cyclic (modulo 3). The vector product is defined by the deter- 
minant 
os 7 


~> 


j 
n= |m, m, : (5.9) 
m m 


= 


(it1)x (i+ Dy (i+1)z 
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Here the sets {x} and {y,} have been chosen to span the space of interest. The 
three—dimensional surface is then determined relative to this grid using Equation 
(5.3). We assume further that an observer is located at the point (x,, y,, z,) which is 
achieved by a rotation (a, B, y) about the x, y, and z axes, respectively. (Note that 
this rotation is not composed of orthogonal components.) This rotation was treated 
in some detail in Chapter 4 and the reader is referred to the routine rotmat() and 
rotpt() for a complete discussion. 

With this formulation, then, we can generate an abstract three-dimensional 
space with the observer located at any point in the space. Following the rotation a 
new set of coordinates is defined by 


x", x, 
y's = Roa, p,y{t y, (5.5) 
f@',,y',) SX» J, 


R(a, B, y) is given by Table 4.1. To display this space it will be useful to collapse 
the x-axis once a suitable rotation has been achieved. The points plotted on this 
display will then be members of the set 


{(0, y', fx!» ¥',,)): n=1,2,....N; m=1,2,...,M} 


The order for the display will be to let {y'} correspond to column positions and 
{f(x', y’,)} correspond to row positions. 

One final concept is needed: the notion of a facet. Basically, for plotting 
purposes it is useful to break the surface into facets (or small localized areas). The 
methodology for achieving this (used here) is to consider a grid structure on the x-y 
plane and assume a facet to be bounded by each set of grid lines projected onto the 
surface. For example, if we consider a surface grid, it is clear that the four x-y plane 
grid points 


1: @, y,, 0) 

2: (x, y,, 9) 

3: (Xiuv y, m+? 0) 
4: Qiy y m? 0) 


define the locations of the vertices of the grid. Lines connecting 1 and 2, 2 and 3, 
3 and 4, and 4 and 1, respectively, define the grid. Projecting these lines onto the 
surface yields the surface points 


I: (X,, y n? f (%,, y »)) 

2: (X,» yma? fix,» Yn) 
3: (Xv y m+P f (Xp y mv) 
4: Xap y nm? fy y, ww) 
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5.4 REEXAMINING THE CORE VERSUS PRESENTATION 
MANAGER API SERVICES 


The core or basic API services are largely derivative from the OS/2 Version 1.0, 
where only keyboard (Kbd), mouse (Mou), video (Vio), and DOS (Dos) calls are 
available. These are the only services treated in this book. For those readers famil- 
iar with Microsoft’s Windows environment, the PM presents a similar graphics-like 
interface. It is programmed in a fashion similar, but not identical, to Windows. Pro- 
gramming the PM requires a great deal of concentration and patience. This effort 
will be simplified greatly when additional object-oriented tools are developed. 
Petzold [11] has written a lengthy book on how to accomplish this Presentation 
Manager programming. The reader is cautioned that some differences exist between 
the PM described in Petzold’s book, which is based on the Microsoft version, and 
the IBM version of the Presentation Manager, which was released after the Micro- 
soft version. When accessing the graphical interface, for example, in the full com- 
mand screen mode the Vio calls must be used. Under PM the Gpi function calls are 
used. 


5.5 ADVANCED C EXAMPLE: A THREE-DIMENSIONAL SURFACE 


In this section we present an analytical approach for describing three-dimensional 
surfaces within the framework of simple vector arithmetic. A technique for remov- 
ing “hidden lines” is illustrated based on consideration of the rotating characteristics 
of facets. Here a facet is a member of a logical subdivision of the three-dimensional 
surface. We begin with a brief discussion of surface characterization. 


Functions of Two Variables 
It is convenient to denote a function of one variable using the notation 


y = fi) (5.2) 
Graphically, such a relationship is represented with a two-dimensional plot using the 
independent variable, x, along the horizontal axis and the dependent variable, y, 
along the vertical axis. When a function depends on two variables it is representable 
in a three-dimensional space defined by 


| z= f(x, y) (5.3) 
In displaying such data a third axis must somehow be represented on a two-dimen- 
sional surface, the display screen. We have seen that it is useful to assume three 
perpendicular (orthogonal) axes: an x-axis, a y-axis, and a z-axis. Points in this space 
are denoted by 
(% y, 2) = & y, f% y)) (5.4) 
The geometry for a three-dimensional surface consists of a grid of x-y points. 


{(X,, Y,» O)}: n = 1, 2, ..., Nj m = 1, 2, ..., M } 
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TABLE 5.3 (Concluded) 


Type Comments 


accessible either sequentially, randomly, or 
directly via indexes or keys. 

Hashing This is a structure technique in which an algorithm 
or function is used to generate an address of a 
data element from a key. Typical associated struc- 
tures would be a hash list. 

Heaps Heaps are most easily described as binary tree 
Structures possessing order and shape. Order, for 
example, might specify that the value at any node 
is less than or equal to the value at the children. 
Shape suggests the tree architecture. 

Linked lists These data structures are used as indexes to other 
Structures and have an associated pointer index 
that points to a relative record in the primary list. 

Priority queues This is a set of elements arranged according to 
priority. When an element is added or deleted, we 
do so in accordance with assigned priority or 
associated rules. 

Sparse arrays These are data structures with many zero elements. 
They can be reduced significantly to smaller 
storage by using additional indexing arrays with 
an appropriate indexing algorithm. 


5.3.3 API Return Values and Error Checking 


When an API routine is called, it contains a return value in the AX register which 
is passed back to the calling routine. In general, if this AX or return value is zero, 
the call has been successful. If not, one of several possible error conditions may 
exist, depending on the value returned. The user has an option as to how to treat 
these calls. 

As an example of a typical API error return processing, consider 


error = DosGetPID(process IDs); 
if (error!=0) 
, 
printf(“Error on acquiring process ID”); 
exit(1); 
} 


eee 


The reader should feel free to insert his or her own error processing as appropriate 
following API service calls. 
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ized algorithms for handling large data organizations that require speed of access of 
optimized storage. Similarly, sparse array techniques minimize the amount of stor- 
age needed for multidimensional data. 


TABLE 5.2 SOME TYPICAL ALGORITHMS 


Type 
Mathematical 
Sorting 


Searching 
String processing 
Geometric 


Graph 


Advanced 


Comments 


Arithmetic, random numbers, interpolation, simultane- 
ous equations, integration 


Exchange, bubble, quicksort, radix, priority queues, 
selection/merging 


Sequential, binary, tree, hashing 

Pattern matching, parsing, file compression 

Polygons, line intersection, convex surfaces, grids, 
closest point 

Connectivity, mazes, shortest path, topological sorting, 
networks 

Systolic arrays, FFT, dynamic programming, linear 
programming 


All these techniques are used in developing the area of data structures and database 
design. The interested reader is referred to reference 9 for specific details of large- 
scale implementations. In this book we will confine most of the discussion to the 
primitive structures listed in the beginning of Table 5.3. 


TABLE 5.3 SOME REPRESENTATIVE DATA STRUCTURES 


Type 


Arrays 


Bit strings 


Bit maps 


Databases 


Comments 


These structures consist of concatenated variables 
stored in a block and accessible via one or more 
indexes. 


These structures constitute the basic building blocks 
of any language and are accessible in C by using 
the bitwise operators. 


This is a mapping of a set of variables and their 
associated parameters onto a set of bits, which 
constitutes a smaller set of storage. All attributes 
of the variables are not represented in this fashion, 
and the mapping must be attribute specific. 


Databases are complex data structures consisting of 
data items or fields collected into records that are 
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increment++t; 


Now consider the alternative 


for (n=1;n<=N;n++) 
{ 
v(nj=v[n]*v[n] 
for (m=1;m<=M;m++) 
{ 
if((v[n]>q{m]) & (v[{n]<q[m+1]})) 
increment++; 
} 
} 
} 


The second form is admittedly more cumbersome, although easier to understand. 
What about time criticality? In the first fragment the expression 


v(n) = v[n)*v{n]j 


is executed NM times, while in the second fragment it executes only N times. The 
latter program fragment ensures an optimum time-critical compiled result. Although 
this example may appear academic, it is representative of the decisions regarding 
form that must be made. 

Algorithm development The topic of this section is algorithms. Algorithms are 
structured approaches to solving mathematically, particular problems amenable to 
solutions. A more general definition would, of course, encompass most programming 
efforts. We have iterative and recursive programming and it is true that a fundamen- 
tal technique in designing efficient solutions is the recursive method, because this 
approach builds on an earlier solution. Table 5.2 illustrates some typical algorithms 
as discussed by Sedgewick [8]. We have already seen examples of some of these 
algorithm techniques. In general, we will not address the complete class of problems 
covered by the table; the interested reader is referred to reference 8 for a complete 
discussion. It is important, however, to recognize that algorithms are what computer 
programs are all about. Problems amenable to algorithmic solution can easily be 
tailored to computers. 

Data Structures We briefly consider the subject of data structures [9] (as opposed 
to file structures [10]). Table 5.3 illustrates some well-known data structures used in 
small- and large-scale program development. We have already seen arrays used as 
a basic element of the C language. Using the bitwise operators, it is possible to en- 
ter or extract information from data elements at the bit level. More complex data 
structures, such as hashed lists, heaps, linked lists, and priority queues, are special- 
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As part of style we need to consider templates. This topic is meant to cover 
the overall program structure. A general template is as follows: 


Module I (main()) 


Documentation (comment describing module) 
Preprocessor (include files, define directions, globals) 
Main() (function definition) 


Module 2 (function1 (),...functionN()) 


Documentation (comment describing functions) 
functionl1() 


functionnNn( ) 


Module 3 (function(N+1)(),...functionM()) 


Documentation (comment describing functions) 
function(N+1) () 


functionM( ) 


ees 


Module L (functionQ(),...functionR()) 


Documentation (comment describing functions) 
functionQ( ) 


functionR( ) 
Here 
1<N<N+1<...<M<...<Q<...<R 
and 
2<3<...<L 


Finally, we consider form. Good form consists of defining the optimum meth- 
odology for implementing an algorithm. Unfortunately, most algorithms are suffi- 
ciently complex that it is difficult to decide what the best way to implement the al- 
gorithm might be. The issue of form must be addressed in a somewhat simplistic 
fashion. Consider the following code fragment: 

for (n=1;n<=N;n++) 

{ 
for (m=1;m<=M;m+t+) 
{ 
v(nj=v[n]*v[(n]j; 
if((v(n}>q[m]) & (v[n]<q{m+1])) 
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5.3.2 Templates, Style, and Form 


Style is a somewhat elusive feature of programming which reflects individual 
thought patterns as much as any organized approach to program development. 
Consider, for example, the problem of variable definition, mentioned earlier. The 
following is easily understood: 


mortgage_int = loan_principal * interest_rate. 
What about the following? 


Instantaneous_amp = exp(—time/delay_factor)* 
/ cos(2. * pi * frequency * time) 


For technically inclined users, the following is much easier: 
A = exp(—t/tau) * cos(2. * pi ef: ®. Ee) 


(Those who are not technically trained probably will not care about such details.) 

Programmers with a background in FORTRAN, ALGOL, or original BASIC 
are familiar with restrictions on the length of a variable name. They tend to be more 
cryptic than programmers of more recent vintage, who are used to 32-character 
limits. This is decidedly a learned style feature. More important is the need to clar- 
ify variable meaning. If the programmer provides a design document, which is 
essential for a clear understanding of the program, each variable should be deline- 
ated in an unambiguous fashion. In cumbersome assignments, spelling out each 
variable name in a wordy fashion can often obscure the meaning of the underlying 
relationship. Similarly, by being too cryptic or obscure, the meaning of the equality 
can escape the reader. 

An additional feature of style is the nature of actual code reduction. In other 
words, is the code compact, or can each relationship be followed in easily readable 
form? The code 


if(((xl==cl) | (x2==+c2)) & ((x3==c3) | (x4==c4))) 
Al; 


is compact, the following is slightly easier to follow: 


if((xl==cl) | (x2==c2)) 
{ ‘ 
if((x3==c3) | (x4==c4)) 
{ 
Al; 
} 
} 


(If the reader has doubts as to which is easier, try assigning values and working out 
the truth table.) 
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structures the use of exception handling must be clarified. Consider the if... state- 
ment in the following form: 


if (check==0) 
{ 
printf ("Denominator zero"); 
exit(1); 
} 


Here the if statement specifically looks for an error condition and prints the message 
explaining this condition prior to exit. The exception handling is part of the if 
purpose. A sequence of the form 


for (n=l; n<=N; n+tt+t) 


{ 
X=xX+a} 
if (x==NTOTAL) 
{ 
printf ("x max exceeded"); 
exit(1); 
} 
a=atb; 
} 


is less desirable because the causative factors (a, b, and x too large) are unclear at 
time of the exit. In general, we use the unconditional exit only [exit (1)] and we 
only use this exit when the complete nature of the error condition is absolutely clear. 
Also, it is used subject to the constraints indicated above. A typical use is 


if ((check=fopen (FN1,"r"))==NULL) 
{ 
printf ("Error on read file open"); 
exit(1); 
} 


To some extent this discussion is semantic. Exits from within loops should not 
occur. Since C does not allow branching or jumps (as in assembler, FORTRAN, and 
other languages), there is really no way to exit a loop except with an exception 
handler or a goto. We have virtually ruled out goto statements, so only exception 
handling remains. The latter exit should be avoided within a loop structure. Flag the 
condition and upon exit from the loop report all relevant parameter data prior to 
exit. The latter exit should be accomplished using a conditional structure that spe- 
cifically tests the exception status. 
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This artifact illustrates what functional activities are subordinate to other activities. 
At a glance, the user can glean overall functional program relationships from the 
program Structure Chart. This entity should be developed as the first component of 
program design. Next, the execution flow must be developed. The functional flow- 
chart serves as a convenient vehicle for accomplishing this. 

Briefly, there are a number of types of flowcharts. They vary from more 
functionally oriented descriptions of program behavior, in which generalized activ- 
ity is interconnected, to very detailed descriptions where each line of code literally 
occupies a place in the overall flowchart. In this book we favor the functional 
approach because it is a good compromise: It gives the user a sense of the program 
execution and does not require pages of description. 

As an alternative to the flowchart, pseudo-code can be used. Pseudo-code has 
the advantage that it is very close to the actual program mechanics and has the 
structure of natural language. With pseudo-code the uninitiated can develop a feel- 
ing for program execution while not fully comprehending the language syntax in 
which the program is written. A number of authors of high-level languages are de- 
veloping program design languages (PDLs) which are essentially pseudo-code. The 
PDL approach to program design is particularly appropriate for very large-scale 
program development that may require significant development time. In this case a 
need exists to have an easily understood design document that can be made avail- 
able to new programming team members. For most microcomputer applications, 
however, the flowchart is quite suitable. 

Actual module implementation within the confines of structured code employs 
sequential and control statements as discussed above. The module should have one 
entry and one exit path (with exception control handled so as to delineate the error 
condition). Finally, each module should be documented to explain its function and 
what data structures exist, where needed. The relationship of one module to another 
can be delineated in special cases where it is not explained in an associated flow- 
chart or Structure Chart. 

The purpose of this short discussion is to reemphasize the importance of struc- 
tured programming in the C language by briefly illustrating several features of the 
language. Also, we discuss some philosophical implications for structured code.We 
begin with the one entry and one exit precept applied to module definition. This 
control mechanism can be extended backward to the architectural structures men- 
tioned earlier. Next we discuss the implications of style and form. (Also, a brief 
look at templates is treated as part of style.) Finally, a general look at algorithm de- 
velopment is used to round out the discussion. Also, data structures are treated. 

The control and loop structures used in the C language are designed to provide 
one entry and one exit to modules. This ensures that control flow is linear through 
the structure (if, if...else, ..., while, do...while, etc.). Also, exit conditions are clearly 
made available to the user during execution. With regard to iterative structures such 
as loops, it is clear that multiple exits can be disastrous because the user may never 
learn about the state of the system that causes the exit condition. To jump outside 
a loop that is undergoing normal execution is highly undesirable. With conditional 
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An example of point 9 would be where very simple “bookkeeping” is involved in 
a module for clarity and maintenance purposes. Also, the use of globals does not ap- 
preciably increase the level of difficulty of a small program but can significantly 
reduce the size of variable handling code (particularly when pointers are used as an 
alternative). 

The major difficulty with software development is not in determining how to 
make the computer function to execute a program but rather, in ensuring that a 
given program actually generates the output it was intended to generate. The empha- 
sis here is on software integrity, with the presumption made that the programmer 
will learn the mechanics of programming within a particular language. To simplify 
program design and development, structured programming techniques evolved. 
Dijkstra [7] defined the initial concept, and structured programming is now a well- 
established discipline which has greatly affected the C architecture. The notion of 
structured programming in the broadest sense encompasses top-down design and 
modular programming. At a more localized level, structured programming focuses on 
coding techniques intended to simplify program understanding and facilitate program 
use (such as program modification and maintenance). In the following discussion we 
focus on the latter area: structured code. 

The most desirable structure concept is sequentially defined code. In this 
instance instructions. are executed as they are encountered. C provides for two 
deviations from this approach: conditional execution and iterative loops. We have 
seen examples of both of these conditions. Conditional execution included use of the 
forms 


bos Vee 

2. if...else 

3. the conditional operator 
4. switch...case...break 


Similarly, iterative loops utilize the forms 


1. while... . 
2. do...while 
3. for... 


These two groups of statements are the most important control mechanisms in the 
C language. They form the basis of C structured coding techniques. Although C 
allows the goto... statement, it is discouraged and appropriate only in very extenu- 
ating circumstances. It should be argued forcefully that any code segment using a 
goto can be rewritten to avoid this statement. The major difficulty with goto state- 
ments, as pointed out by Dijkstra, is that unrestrained branching within a module 
can take place. This can lead to difficulty in understanding the intent of the code. 

Structured code begins with a hierarchical description in the Structure Chart. 
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2.17. 


Answers To Problems 


pendent thread has a particular piece of code that must execute prior to any other 
operation for the parent process. Then it would be desirable to monitor and ensure 
that this code executed, before continuing. Clearly, this could be dynamic and change 
with the active chronology of execution. 


DosExit is used to terminate an application and return to OS/2. All other returns 
NEAR or F. 


Chapter 3 


3.1. 


3.2. 


3.3. 


3.4. 


3.5. 


The drivers mentioned operate from the kernel, level 0. They must originate here 
because they have to be protected ahead of all other code. We cannot have a disk- 
write preempted in the middle, nor can we tolerate “jerky” mouse cursor movement 
as the mouse position changes. 


The macro calls admittedly remove a layer of detail from the program code. This 
layer would tend to expand the code by a factor of 4 to 7. All the pushes to the 
stack have been suppressed prior to each API call and the call takes on the form of 
a higher-level-language (HLL) function call. The data area tends to expand consid- 
erably with all the macro parameter definitions, but the actual executable code re- 
mains compact. This requires the programmer to develop a general familiarity with 
the macro calls at the level of the IBM Programmer’s Toolkit or Appendix C of this 
book. Once this familiarity has developed it is a very easy matter to read the result- 
ing “structured” code and follow the flow of execution. Hence maintenance becomes 
an easy task. Clarity (of how the code executes) is also paramount, and much more 
so under the macro call format. The macro calls do, however, inhibit debugging in 
that the in-line code is missing. If the user prints a copy of the list file with macros 
expanded, tracing the source code is still an easy matter. In general, these approaches 
tend to be a matter of preference based on the programmer’s orientation. We favor 
the HLL appearance of the code. It makes functional performance of the code the 
primary mechanism to be emphasized. Expansion of the in-line code makes it more 
obscure from a functional viewpoint but easier (and essential) to debug. 


For the segment to be sharable, bit 0, to be sharable through @DosGiveSeg, or bit 1, 
to be sharable through @DosGetSeg, must be set in the flags word (the third pa- 
rameter in the calling list). Bit 2 of this same flags word must be set if the segment 
is to be discardable. 7 


The write to the huge segment must use the proper selector. When crossing the 64K- 
byte boundary the program must access a new but contiguous selector. 


There must be some common link between the two processes. Usually, this is a 
common element name such as 


\SEM\SDAT.DAT 
or 
\QUEUES\QDAT. DAT 


which appears in both processes and is the same. The system then provides the con- 
nection. Alternative to this is the passing of a selector or printer in a common 
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2.7. 


2.8. 


2.9. 


2.10. 


2.11. 


2.12. 


2.13. 


2.14, 


2.15. 
2.16. 


kbd_buf db 80 

lkbd_buf dw $~kbd_buf 

iowait dw 0 

kbdhdl equ 0 

freq dw 1000 

dur dw 5000 

@KbdStringin kbd _buf,1lkbd_buf,iowait,kbdhdl 

@DosBeep freq,dur 

Yes, all calls to the API can be made in full form, where each push and pop, as 


well as EXTRN declaration, is stated explicitly according to the rules of OS/2. The 
toolkit simply provided a set of assembler .inc files and C .h files that facilitated 
usage of the API services through very functional macros. 


The key assumption is that segment selectors can be treated as segment addresses. 
Since the 80286 accesses segments using the selectors, the selector value must reside 
in a segment register. The address is then calculated in the usual Protected Mode 
fashion, where the segment selector acts as a segment address. The use of segment 
override addressing, such as 


es:[(bp] 


simply permits specification of an address in the usual fashion, where the segment 
selector is made to correspond to the physical segment address when VioGetPhysBuf 
is exercised. 


They represent FAR locations because the entry points are called from external API 
modules, hence a 32-bit address must be specified. 


No hierarchy should have a single child subordinate to a parent. The box 310 should 
be absorbed in 300. 


The command is 
@DosWrite dev_hand,in_buffer5,bytesin3,bytesout 
where the undefined parameter is 


in buffer5 db 1BH,41H,0CH 


It is intuitive that they cannot be preempted by an OS/2 task switch, or the possibil- 
ity of losing data from the device would occur. 


To access the screen buffer (physical) properly, the screen must be locked; hence if 
scr_ld is to load scr_buffer with the screen context, it must be locked. If prtscr is 
executed when the screen is locked, it could dominate access time for the physical 
display buffer. Hence the program should load a temporary buffer, release the screen 
context, and then begin the print operation. 


Ten complete raster segments. 


The DosExitCritSec corresponds to exit of a critical section of execution for a thread 
and returns control to a process. This could be used, for example, when an inde- 


320 


2.2. 


2.3. 


@vioGetPhysBuf 


@VioScrLock 


macro 
@define 
@pushs 
@pushw 
call 
endm 


macro 
@define 
@pushw 
@pushw 
@pushw 
call 
endm 


Answers To Problems 


dstruc,rsrvd 
VIOGETPHYSBUF 

dstruc 

rsrvd 

far ptr VIOGETPHYSBUF 


wait,status,handle 
VIOSCRLOCK 

wait 

status 

handle 

far ptr VIOSCRLOCK 


2.4. The VioGetPhysBuf structure, PVBPtr1, needs to be specified as 


2.5. 


2.6. 


eee 


PVBPtrl 
bufstl 

buflenl 
physell 


freq 
dur 


@DosBeep 


waitf 
dstat 
viohdl 
PVBPtrl 
bufstl 
buflenl 
physell 


ooe#@ 


@VioScrLock 
@VioGetPhysBuf 
push physell 
pop es 

mov dh,25 
mov, da1,154 
mov bx,75 

mov cx,235 
call connl2 
@VioScrUnLock 


eee 


label FAR 

dd 0A0000H 

dd 6D60H 

dw 0 

dw 5000 

dw 1000 
freq,dur 

equl 

db ? 

equ 0 

label FAR 

dd 0B8000H 

dd 4000H 

dw 0 

waitf,dstatk,viohdl 

PVBPtr1,viohdl 

viohdl 
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1.10. 


1.11. 


1.12. 


1.13. 


1.14, 


1.15. 


1.16. 


1.17. 


1.18. 
1.19. 


1.20 


This occurs as a result of IBM’s reservation of the last 384 KB of address space for 
special-purpose system memory, much of which is either screen buffer memory or 
ROM (read-only memory). OS/2 extended memory resides from 1 MB to 16 MB (in 
the physical address space). 


Physical memory occupies the actual hardware locations accessed by the 24 pins 
from the address lines of the 80286 CPU chip. This can be a maximum of 16 MB 
(224), Virtual memory is memory allocated in an abstract sense by the system. Since 
there are 16,384 (2'*) possible selectors with 65,536 locations per selector, there are 
a maximum total of 1,073,741,824 possible locations that can be addressed uniquely 
in this virtual space. OS/2 manages this space by mapping each segment selector to 
a segment base address through manipulation of the translation registers. Hence, if 
the available physical memory is less than 16 MB, for example, and the required 
program and data memory exceed 16 MB or the actual physical memory, OS/2 will 
move code and data to and from disk as needed. 


The Table Indicator (TI) bit in the segment selector is set for references to system 
memory. It is zero for references to local application program memory. There are 
536,870,912 locations accessible by applications in virtual memory. 


If the data communications service resided at level 0, it could preempt the CPU dur- 
ing long sessions which would mask out other, potentially more important interrupts. 
This could lead to catastrophic failure. 


The boot record loads the Machine Status Word register with a MSW that has bit 
zero set for Protected Mode operation. Subsequent loads of this register using the 
LMSW instruction can modify this state. 


1. Initialization Routine—Assembler 
2. Strategy Routine—C 
3. Interrupt Service Routine—Assembler 


A pipe references a bulk memory area, whereas a queue allows access to individual 
members of the queue. 


The API framework is more cumbersome for assembly language programs where 
software interrupts (using INT) provide immediate low-level access to the system 
hardware, for example. On the other hand, the API call orientation allows a rather 
elegant description of the services, which can enhance understanding and readability. 
In the C environment the API services are an asset, providing very readable function- 
like access to system services. 


In both cases the threads must synchronize their access. 


DosSleep. Unlike a process, the thread cannot terminate itself. Threads can be ter- 
minated only when the thread’s parent process is terminated. 


. No, the Gpi services can be used only with the PM. 
1.21. 


Modaless because the screen context is not preempted. 


Chapter 2 


2.1. 


(a) pins 8, 6, 4, 3, and 2 
(b) pins 8, 7, 4, 2, and 1 
(c) pins 7, 5, 3, and 
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extrn callname:far 
endif 
endm 
1.5. @VioScrUnLock macro handle 

@define VIOSCRUNLOCK 
@pushw handle 
call far ptr VIOSCRUNLOCK 
endum 

where 

@pushw macro parm 
mov ax,parm 
push ax 
endm 

and 

@define macro callname 
ifndef callname 
extrn callname: far 
endif 
endm 

1.6. @VioScrLock macro wait,status,handle 

@define VIOSCRLOCK 
@pushw wait 
@pushs status 
@pushw handle 
call far ptr VIOSCRLOCK 
endm 


where @define and @pushw are defined as in the answers to Problems 1.4 and 1.5 


and 

@pushs macro parm 
mov ax,SEG parm 
push ax 
lea ax,parm 
push ax 
endm 


1.7. 1. A multitasking environment 
2. A memory management facility 
3. The PM user-friendly interface 


1.8. Since we are talking about applications code, the non-system-oriented instruction set 
is applicable, and this is generally common to both CPUs with few exceptions. The 
major drawback to 80386 code is the use of references to the extended register set 
(32-bit registers): EAX, EBX, ECX, ... . While the 80286 general-purpose registers 
(AX, BX, CX, ...) are a subset of these extended registers, the converse is not true. 


1.9. 2 


Answers To Problems 


Chapter 1 


1.1. 


81CA H 


1.2. No, while OS/2 employs time slicing to share access to a single CPU among mul- 
tiple separate tasks or threads, it is not designed to service more than one CPU. 
Hence OS/2 does not provide for the parallel operation of multiple CPUs. 


4, 294, 967, 295 (232— 1); +2, 147, 483, 647 (23!— 1) 


1.3. 
1.4. 


@DosExit macro 
@define 
@pushw 
@pushw 
call 
endm 
where 


@pushw macro 
Mov 
push 
endm 

and 


@define macro 
ifndef 


action,result 
DOSEXIT 

action 

result 

far ptr DOSEXIT 


parm 
ax,parm 
ax 


callname 
callname 
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TABLE E.2 (Concluded) 


App.E ‘Keyboard and Mouse Kernel Functions 


Service Description 

MouGetDevsStatus Getting the state of the pointer and the event 
queue 

MouReadEventQue Reading a data record from the event queue 

MouGetNumQueE! Determining the number of records in the queue 

MouFlushQue Clearing the queue 

MouRemovePtr Defining a restricted screen area where the 

pointer is not allowed to appear 

MouFlushQue Clearing the queue 

MouRemovePtr Defining a restricted screen area where the 
pointer is not allowed to appear 

MouDrawPtr Redefining a restricted screen area, where the 
pointer is allowed to appear 

MouGetPtrShape/ Getting or setting the shape of the pointer 

MouSetPtrShape 
MouGetPtrPos/ Getting or setting the vertical and horizontal 
MouSetPtrPos positions of the pointer 

MouRegister Registering another mouse subsystem for the 
current session 

MouDeRegister Canceling the registration of a mouse subsystem 

MouSynch Synchronizing access for a mouse subsystem 


with the mouse device driver 


REFERENCE 


1. IBM Operating System/2 Programmer’s Toolkit, International Business Machines Corpo- 
ration, Boca Raton, FL, 1987. 
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TABLE E.1 (Concluded) 
Service 

KbdFlush 

KbdOpen/kbdClose 


KbdGetFocus/ 
KbdFreeFocus 


KbdGetStatus/ 
KbdSetStatus 


KbdGetCP/ 
KbdSetCP 


KbdSetCustXt 
KbdRegister 


KbdDeRegister 
KbdSynch 


Description 


Clears the keyboard input buffer of all queued 
keystrokes 


Opening and closing a handle to a secondary logical 
keyboard 


Getting and releasing the input focus by the second- 
ary keyboard 


Getting and setting the keyboard state 


Getting and setting the ID of the system code page 
used to translate scan codes into ASCII codes 


Installing a customized keyboard translation table 


Registering a keyboard subsystem for the current 
session 


Canceling the registration of a keyboard subsystem 
Synchronizing the subsystem’s access to the physical 


keyboard 


E.3 THE MOUSE SERVICES 


Table E.2 indicates the mouse API services. Again, these services are available 
through the macros and functions defined in the IBM Toolkit. 


TABLE E.2. THE MOUSE FUNCTION CALLS 


Service 
MouOpen 


MouClose 


MouGetNumButtons 


MouGetEventMask/ 
MouSetEventMask 


MouSetDevstatus 


MouGetNumMickeys 


MouGetScaleFact/ 
MouSetScaleFact 


Description 


Initializes the mouse event queue and obtains a 
handle to access it 


Closes the mouse device for the current session 
and removes the mouse device driver handle 
from the list of valid open mouse device 
handles 

Determining the number of buttons supported 


Getting or setting the types of events reported by 
data records 

Setting mouse data to be returned in mickeys 
instead of coordinates (a mickey is a unit of 
measurement for physical mouse motion, 
whose value depends on the mouse device 
driver currently loaded) 

Determining the number of mouse motion units 
per centimeter 


Getting or setting the mickey-to-pel ratio for 
mouse motion 
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BSE.H 
This file allows the user to set up defined symbols such as all 
the OS/2 API kernel functions, including those that begin with 
Dos, kbd, Vio, and Mou. It includes loading of BSEDOS.H, 
BSESUB.H, and BSEERR.H. 

Level 3: OS/2 

BSEDOS.H 
This file sets up constants, structures, and function prototypes for 
the Dos services. 

BSESUB.H 
This file sets up constants, structures, and function prototypes for 
the Vio, kbd, and Mou services. 

BSEERR.H 
This file sets up error code constants for the OS/2 kernel API 
services. 


The remaining .h files are Presentation Manager files and are only available under 
the OS/2 1.1 or higher. The .inc files are defined as follows: 


Level 1: SYSMAC.INC 
This file sets up all the API macros by calling DOSCALLS.INC 
and SUBCALLS.INC. 
Level 2: OS/2 kernel 
DOSCALLS.INC 
This file sets up all macros for Dos calls. 
SUBCALLS.INC 
This file sets up all macros for kbd, Mou, and Vio cails. 


E.2 THE KEYBOARD SERVICES 


Table E.1 illustrates the keyboard services. These are available with the IBM OS/2 
Toolkit referenced throughout the book. 


TABLE E.1 KEYBOARD FUNCTION CALLS 


Service | Description 
KbdStringIn Reads a string from the keyboard and loads a buffer 
KbdCharIn Reads a character and loads the associated internal 
structure 
KbdPeek Allows examination of a character data record 
without removing it from the buffer 
KbdXlate Translates a scancode and shift key state into an 


ASCII character code, using the code page set for 
the keyboard 


E Keyboard and Mouse 
Kernel Functions 


In this book we describe the OS/2 Kernel API services which are used to access the 
full-screen mode. In this appendix we discuss the keyboard and mouse services. 
These calls cannot be used in a Presentation Manager application. 


E.1 ACCESSING THE TOOLKIT 


To employ the Toolkit functions [1] the programmer must resort to defining and 
using various assembler and C structures and databases that contain parameter infor- 
mation. These structures and data types are contained in a set of files, with exten- 
sion .inc for the assembler and a set of files with extension .h for the C compiler. 
The .h files are defined as follows (we use .h and .H interchangeably): 


Level 1: OS/2 and Presentation Manager 
OS2.H (includes OS2def.H, BSE.H, and PM.H) 
This file sets up the compiler for access to all OS/2 definitions, 
base include files, and files needed to define Presentation Man- 
ager data types, functions, and structures. 
Level 2: OS/2 
OS2DEF.H 
This file defines common constants, data types, error codes, and 
structures needed to OS/2 kernel access. 
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TABLE D.1 (Concluded) 


Program Description Page 
dyn22.def Definition file for load on call 236 
dyn2.asm Assembler program for run-time DLL 238 
dyn33.def Definition file for dyn2.asm 239 
gen3d.c C program that generates a surface 255 
xadiskw.c Diskwrite 256 
mmain3d.c Main calling program for 3D surface 257 
xadiskr.c Diskread 260 
xscale.c Scales array for mmain3d.c 261 
facet3d.c Generates facets for mmain3d.c 262 
gphrout.c Plot routines 263 


Table D.2 MAKE Files Used in Text 


Program Description Page 
ioprgm.mak MAKE file for ioprgm.c 173 
swave.mak MAKE file for swave.c 178 
prtwave.mak MAKE file for prtwave.c 184 
pipestc.mak MAKE file for pipestc.c 197 
pipeclc.mak MAKE file for pipeclc.c 197 
ckthred.mak MAKE file for ckthred.c 198 
dja.mak MAKE file for dja.c 212 
gen3d.mak MAKE file for gen3d.c 254 


mmain3d.mak MAKE file for mmain3d.c 256 
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TABLE D.1 


Program 


prtscrm.asm 
nos2512.asm 


nos261.asm 
nos252.asm 
memseg.asm 
hugeseg.asm 
suballo.asm 
ckthl.asm 


unos251l.asm 
nnos252.asm 
ckprl.asm 


os2p2.asm 
pipest.asm 
pipecl.asm 
queuest.asm 
queuecl.asm 
loprgm.c 
swave.c 
gphrout.c 
prtwave.c 
pprtscr.c 
pipestc.c 
pipecic.c 
ckthred.c 
tetra.c 
rotetra.c 
rotmat.c 
rotpt.c 
DMApoint.c 
timhist.c 
dja.c 
scales.c 
scales1.asm 
dynl.asm 
dlink1.asm 
dyninit.asm 


Programs Used in This Book 


Description 


Modified prtscr.asm used with twolnm.asm 


_ Creates shared segment, child process, and prints 


screen 

Child process that generates random numbers 
Supplemental routines needed by nos2512.asm 
Program that creates and reallocates memory 
Program that allocates a huge segment 
Program that suballocates memory 


Program that sets up two threads using RAM 
semaphores 


Uses multiple threads to generate a box 
Support routines for unos251.asm 


Program that sets up two processes using system 
semaphores 


Child process using system semaphores 

Pipe main setup program _ 

Child process for pipe communications 

Queue main setup program 

Child process for queue example 

C program to illustrate Protected Mode 

C program to plot dynamic sinewave 

C graphic routines used in cgraph.lib 

C program to print sinewave 

C program to print screen 

C program counterpart to pipest.asm 

C program counterpart to pipecl.asm 

C program that creates a child thread 

C program for rotating tetrahedron 

C program that sets up tetrahedron 

C program that calculates rotation matrices 

C program that rotates a point 

C program that removes a point from the display 
C program that creates time-history/value database 
C program that plots Dow Jones activity 

C program to generate musical scales 
Assembler routine to generate scales 
Assembler program for preloaded DLL routines 
Assembler routine that is DLL for dynl.asm 
Initialization routine for DLL 
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Page 


101 
106 


111 
113 
117 
122 
126 
132 


136 
141 
146 


149 
152 
155 
158 
161 
172 
180 
183 
186 
190 
194 
196 
199 
205 
208 
209 
209 
211 
212 
213 
225 
226 
232 
234 
235 


D Programs Used 
InN Tnis BOOK 


In this appendix we list the programs used in this book. Table D.1 presents each 
program, a brief description, and the page number corresponding to the peer 
Table D.2 contains the MAKE files that appear in the text. 


TABLE D.1 PROGRAMS CONTAINED IN THE TEXT 


Program Description Page 
ptr2.asm Assembler program to print “74” to generate line 46 
boxprt1l.asm ' Assembler program to plot two lines to display 36 
scrld.asm Assembler procedure to load screen buffer 62 
prtscr.asm Assembler procedure to print the screen 65 
twoln.asm Assembler procedure to plot/print two lines 69 
graphl.asm Partial contents of GRAPHLIB.LIB 72 
connl2.asm Procedure to plot connected line 76 
slopeln.asm Program to plot connecting line 78 
bbox1.asm Procedure to generate a box 82 
llinev.asm Procedure to generate a vertical line 83 
bbox.asm Program to plot/print box 84 
twolnm.asm Modified twoln.asm that creates a screen buffer 97 
scrldm.asm Modified scrld.asm used with twolnm.asm 100 
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App. C 


@VioScrLock 


Function Declarations and Macros Used to Interface the API 


macro 
@def 
@pw 
@ps 
@pw 
call 
endm 


use: Figure 2.3, 2.7b, 2.8, 2.10, 2.15, 3.1, 3.6, 3.18b, 3.19 


@VioScrUnLock 


macro 
@def 
@pw 
call 
endm 


use: Figure 2.3, 2.7b, 2.8, 2.10, 2.15, 3.1, 3.4, 3.6, 3.18b, 3.19 


@VioScrollUp 


macro 
@def 
@pw 
@pw 
@pw 
@pw 
@pw 
@ps 
@pw 
call 
endm 


ml, m2, m3 

VIOSCRLOCK 

ml swaitflag 
m2 sstatus 

m3 shandle 
far ptr VIOSCRLOCK 

ml 

VIOSCRUNLOCK 

ml s;selector 
far ptr VIOSCRUNLOCK 

ml, m2, m3, m4, m5, m6, m7 
VIOSCROLLUP 

ml ;top 

m2 sleft 

m3 sbottom 

m4 sright 

m5 snumber lines 
m6 sattribute 
m7 shandle 


far ptr VIOSCROLLUP 


use: Figure 2.3, 2.8, 3.6, 3.17b, 3.18b, 3.20b, 3.22b 


@VioSetMode 


macro 
@def 
@ps 
@pw 
call 
endm 


ml, m2 

VIOSETMODE 

ml smodedata 
m2 shandle 


far ptr VIOSETMODE 


use: Figure 2.3, 2.7b, 2.10, 2.15, 3.1, 3.4, 3.18b 


@VioWrtTTY 


macro 
@def 
@ps 
@pw 
@pw 
call 
endm 


ml, m2, m3 


VIOWRTTTY 

ml ;charstr 
m2 ;length 

m3 shandle 


far ptr VIOWRTTTY 


use: Figure 3.17b, 3.20b, 3.21b, 3.23b, 3.24b 
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@DosSubSet 


use: Figure 3.15 


@DosWrite 


use: Figure 2.1, 2.6b, 3.3, 3.22b 


@DosWriteQueuel 


use: Figure 3.25b 


@KbdStringIn 


use: Figure 2.3, 2.2b, 2.10, 2.15, 


@VioGetPhysBuf 


use: Figure 2.3, 2.7b, 2.8, 2.10, 2.15, 3.1, 3.4, 3.6, 3.18b, 3.19 


macro 
@def 
@pw 
@pw 
@pw 
call 


macro 
@def 
@pw 
@ps 
@pw 
@ps 
call 
endm 


macro 
@def 
@pw 
@pw 
@pw 
@pd 
@pw 
call 
endm 


macro 
@def 
@ps 
@ps 
@pw 
@pw 
call 
endm 


macro 
@def 
@ps 
@pw 
call 
endm 


ml, m2, m3 
DOSSUBSET 

ml 

m2 

m3 

far ptr DOSSUBSET 


ml, m2, 
DOSWRITE 
ml 
m2 
m3 
m4 
far ptr DOSWRITE 


m3, m4 


ml, m2, m3, m4, m5 
DOSWRITEQUEUE1 

ml 

m2 

m3 

m4 

m5 

far ptr DOSWRITEQUEUE] 


ml, m2, m3, m4 
KBDSTRINGIN 

ml 

m2 

m3 

m4 

far ptr KBDSTRINGIN 


3.1, 3.4, 3.18b 


ml, m2 

VIOGETPHYSBUF 

ml 

m2 

far ptr VIOGETPHYSBUF 


Function Declarations and Macros Used to Interface the API 


sselector 
s;flags 
*size 


shandle 
sbuffer 
; length 
;byteswritten 


shandle 
;request 
; length 
sbuffer 
;priority 


sbuffer 
;length 
siowait 
shandle 


s;structure 
sreserved 
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use: Figure 3.24b 


@DosReAllocSeg 


use: Figure 3.8 


@DosSemClear 


call 
endm 


macro 
@def 
@pw 
@pw 
call 
endm 


macro 
@def 
@pd 
call 
endm 


use: Figure 3.17b, 3.21b, 3.23b 


@DosSemSet 


macro 
@def 
@pd 
call 
endm 


use: Figure 3.17b, 3.20b, 3.22b 


@DosSemWait 


macro 
@def 
@pd 
@pd 
call 
endm 


use: Figure 3.17b, 3.20b, 3.22b 


@DosSubAlloc 


use: Figure 3.15 


macro 
@def 
@pw 
@ps 
@pw 
call 
endm 


far ptr DOSREADQUEUE 


ml, m2 

DOSREALLOCSEG 

ml 

m2 

far ptr DOSREALLOCSEG 


ml 

DOSSEMCLEAR 

ml 

far ptr DOSSEMCLEAR 


m1 

DOSSEMSET 

ml 

far ptr DOSSEMSET 


ml, m2 

DOSSEMWAIT 

ml 

m2 

far ptr DOSSEMWAIT 


ml, m2, m3 
DOSSUBALLOC 

ml 

m2 

m3 

far ptr DOSSUBALLOC 


ssize 
s;selector 


shandle 


shandle 


shandle 
stimeout 


;selector 
soffset 
ssize 
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@pw m5 sattribute 
@pw m6 ;openflag 
@pw m7 ; openmode 
@pd m8 70 
call far ptr DOSOPEN 
endm 

use: Figure 2.1, 2.6b 

@DosOpenQueue macro ml, m2, m3 

@def DOSOPENQUEUE 
@ps m1 ;owner ID 
@ps m2 shandle 
@ps m3 sname 
call far ptr DOSOPENQUEUE 
endm 

use: Figure 3.25b 

@DosOpenSem macro ml, m2 

@def DOSOPENSEM 
@ps m1 ;handle 
@ps m2 ;name 
call far ptr DOSOPENSEM 
endm 


use: Figure 3.21b, 3.23b 


@DosRead Macro ml, m2, m3, m4 
@def DOSREAD 
@pw m1 ;handle 
@ps m2 sbuffer 
@pw m3 ;length 
@ps m4 ;bytesread 
call far ptr DOSREAD 
endm 


use: Figure 3.23b 


@DosReadQueue macro ml, m2, m3, m4, m5, m6, m7, m8 
@def DOSREADQUEUE 


@pw ml ;handle 
@ps m2 ; request 
@ps m3 ;length 
@ps m4 ;address 
@pw m5 ;code 

@pw m6 | ;nowait 
@ps m7 ;priority 


@pd m8 ;semhandle 
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use: Figure 3.12 


@DosGetShrSeg 


use: Figure 3.5, 3.23b 


@DosGiveSeg 


use: Figure 3.25b 


@DosKillProcess 


call 
endm 


macro 
@def 
@ps 
@ps 
call 
endm 


macro 
@def 
@pw 
@pw 
@ps 
call 
endm 


macro 
@def 
@pw 
@pw 
call 
endm 


far ptr DOSGETHUGESHIFT 


ml, m2 

DOSGETSHRSEG 

m1 

m2 

far ptr DOSGETSHRSEG 


ml, m2, m3 
DOSGIVESEG 

ml 

m2 

m3 

far ptr DOSGIVESEG 


ml, m2 
DOSKILLPROCESS 
ml 

m2 


far ptr DOSKILLPROCESS 


use: Figure 3.4, 3.20b, 3.22b, 3.24b 


@DosMakePipe 


use: Figure 3.22b 


@DosOpen 


macro 
@def 
@ps 
@ps 
@pw 
call 
endm 


macro 
@def 
@ps 
@ps 
@ps 
@pd 


ml, m2, m3 
DOSMAKEPIPE 

ml 

m2 

m3 

far ptr DOSMAKEPIPE 


ml, m2, m3, m4, m5, 
DOSOPEN 

ml 

m2 

m3 

m4 
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;name 


sselector 


scaller sel 
;process ID 
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;recipient sel 


saction 
sresult 


sxead hdl 
swrite hdl 


;size 


m7, 


;name 


shandle 
saction 


*size 
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call 
endm 


use: Figure 3.20b, 3.22b 


@DosCreateThread macro 


far ptr DOSCREATESEM 


ml, m2, m3 


Function Declarations and Macros Used to Interface the API 


@def DOSCREATETHREAD 

@pd ml saddress 
@ps m2 sthread ID 
@pd m3 send stack 
call far ptr DOSCREATETHREAD 

endm 


use: Figure 3.17b, 3.18b 


@DosExecPgm macro ml, m2, m3, m4, m5, m6, m7 
@def DOSEXECPGM 
@ps / mil ;name buffer 
@pw m2 slength 
@pw m3 ;flags 
@ps m4 ;argpointer 
@ps m5 ;envpointer 
@ps m6 ;retrun 
@ps m7 ;pgmpointer 
call far ptr DOSEXECPGM 
endm 
use: Figure 3.4, 3.20b, 3.22b, 3.24b 
@DosExit macro ml, m2 
@def DOSEXIT 
@pw m1 ;action 
@pw m2 ;result 
call far ptr DOSEXIT 
endm 
use: all processes 
@DosFreeSeg macro ml 
@def DOSFREESEG 
@pw ml ;selector 
call far ptr DOSFREESEG 
endm 
use: Figure 3.1, 3.4, 3.5, 3.12, 3.15, 3.24b, 3.25b 
@DosGetHugeShift macro ml 
@def DOSGETHUGESHIFT 
@ps ml sshiftcount 
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@DosAllocShrSeg macro 


use: Figure 3.4, 3.22b 


@DosBeep 


@def 
@pw 
@ps 
@ps 
call 
endm 


macro 
@def 
@pw 
@pw 
call 
endm 


ml, m2, m3 
DOSALLOCSHRSEG 


far ptr DOSALLOCSHRSEG 


ml, m2 

DOSBEEP 

ml 

m2 

far ptr DOSBEEP 
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sno. bytes 
;name 
sselector 


shertz 
sduration 


use: Figure 3.17b, 3.18b, 3.20b, 3.21b, 3.22b, 3.23b, 3.24b, 3.25b 


@DosClose 


macro 
@def 
@pw 
call 
endm 


use: Figure 2.1, 2.6b, 3.3, 3.4 


@DosCloseQueue 


use: Figure 3.24b, 3.25b 


macro 
@def 
@pw 
call 
endm 


@DosCreateQueue macro 


use: Figure 3.24b 


@DosCreateSem 


@def 
@ps_ 
@pw 
@ps 
call 
endm 


macro 
@def 
pw 
@ps 
@ps 


ml 

DOSCLOSE 

ml 

far ptr DOSCLOSE 


ml 
DOSCLOSEQUEUE 
ml 


far ptr DOSCLOSEQUEUE 


ml, m2, m3 
DOSCREATEQUEUE 


far ptr DOSCREATEQUEUE 


ml, m2, m3 
DOSCREATESEM 


shandle 


shandle 


shandle 
;priority 
>name 


sno exclusive 
shandle 
sname 
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@ps macro ml spush address 
mov ax, SEG ml 
push ax 
mov ax, OFFSET ml 
push ax 
endm 

@pd macro ml spush doubleword 
push ds 
push bx 
Mov ax, SEG ml 
MOv das, ax 
mov bx, OFFSET ml 
push word ptr [bx] 
mov ax, [bx+2] 
push bp 
push sp 
pop bp 
xchg [bp+6], ax 
pop bp 
mov ds, ax 
pop ax 
pop bx 
push ax 
endm 


With these preliminary macros defined it is now possible to define the macro calls 
used in the book. 


@DosAllocHuge macro ml, m2, m3, m4, m5 
@def DOSALLOCHUGE 


@pw ml ;no. segments 
@pw m2 ;size last seg 
@ps m3 ;selector 
@pw m4 ymax seg 
@pw m5 *flags 
call far ptr DOSALLOCHUGE 
endm 
use: Figure 3.12 

@DosAllocSeg Macro ml, m2, m3 
@def DOSALLOCSEG 
@pw m1 sno. bytes 
@ps m2 ;selector 
@pw m3 ;flags 
call far ptr DOSALLOCSEG 
endm 


use: Figure 3.1, 3.8, 3.15, 3.25b 
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points determined by symbols such as INCL_BASE. Typically, these include files 


are: 
Level 1 (OS/2): 
Level 2 (OS/2): 


Level 3 (OS/2): 


Level 2 (PM): 


Level 3 (PM): 


os/2.inc (includes os/2.def.inc.bse.inc, and pm.inc) 
os/2def.inc (defines constants, types, error codes, and struc- 
tures) 

bse.inc (includes bsedos.inc, bsesub.inc, and bseerr.inc) 
bsedos.inc (defines constants, structures, and prototypes for 
the Dos API) 

bsesub.inc (sets up calls for Vio, Kbd, and Mou API) 
bseerr.inc. (sets up error code constants for all API calls) 
pm.inc (includes pmwin.inc, pmgpi.inc, pmdef.inc, 
pmavio.inc, pmspl.inc, pmpic.inc, pmord.inc, pmbitmap.inc, 
pmfont.inc) | 

pmwin.inc (sets up windows, message manager, keyboard, 
mouse, and dialog manager API calls) 

purgpi.inc (sets up Gpi API calls) 

pmdev.inc (sets up device context API calls) 

pmavio.inc (sets up the PM Vio API calls) 

pmspl.inc [sets up the spool (Spl) API calls] 

pmpic.inc (sets up the picture API calls) 

pmord.inc (sets up the GOCA orders for the Gpi API calls) 
pmbitmap.inc (sets up the bitmap types) 

pmfont.inc (sets up the types for fonts) 


These include files contain macros for loading API service routines and push- 
ing the stack with appropriate parameter data. In this appendix it is desirable to 
present a similar set of macro-based or function calls used in the assembly language 
in this book. These macros bridge the gap between the macro calls used in the text 
and the actual assembler code required to lead a particular API service. They are 
very similar to the macros available through the Toolkit. We ignore the error-pro- 
cessing features of the Toolkit macros and leave the addition of these features to the 
reader. With these thoughts in mind, let us begin with several subordinate macro 


definitions: 


@pw 


@def 


macro ml ;push word 

mov ax,ml 

push ax 

endm 

macro | nm ;define API entry 
ifndef nm 

extrn nm: far 

endif 


endm 


C Function Declarations 
and Macros Used 
to Interface tne API 


The IBM Programmer’s Toolkit Versions 1.0 and 1.1 [1.2] contain a set of assem- 
bler macros and C function declarations that provide interfaces to the API services. 
In addition, Version 1.1 contains macros and C function declarations for accessing 
the Presentation Manager (PM). In this appendix we address similar interfaces for 
C and assembler and provide the relevant code for the macro calls (assembler) and 
function declarations (C) used in this book. The reader is referred to the Toolkit for 
a complete discussion of similar macros and function declarations. 


C.1 THE ASSEMBLER INTERFACE 


The primary assembler include file in Version 1.0, and available under Version 1.1, 
iS | 
sysmac.inc 


This, in turn, calls 


doscalls.ine 
subcalls.ine 


which loads Dos, Mou, Kbd, and Vio service macros. 
Under Version 1.1, a new set of include files is provided with variable entry 
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We can use pointers to access this structure through the same approach; for ex- 
ample, the fifth element can be accessed using 


pear _ type -> 


These two statements have identical results. 

In a structure, space is reserved for each element. In a union, space is reserved 
only for the largest element; all other elements must share this space. For example, 
in the following template: 


union 


{ 

int c; 

int d; 

float g; 

double h; 

} letter, *pletter; 


the largest amount of space reserved for the union is 8 bytes with the h variable. All 
the remaining variables must share the space in storage with this variable amount. 
Since c and d each occupy 2 bytes and g occupies 4 bytes, this union can be used 
to store c, d, and g simultaneously, or, alternatively, h or other combinations less 
than or equal to 8 bytes. 

This discussion completes our brief look at C. We have attempted to touch 
only on those syntax features that are used in programming the OS/2 Kernel. 
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In many respects C is the language of choice for programming the API once 
the programmer obtains a familiarity with its features. Certainly, C is the choice for 
programming the Presentation Manager [5]. 

The structure for a function in C has the following form: 


function_name() 
formal parameter types 


{ 


local parameter types 
statements 


return expression; 


} 


Here the lines of code immediately following the function definition statement 
contain the typing for formal parameters. The function brackets are next, with the 
local parameter typing contained within the function brackets, together with all re- 
maining function statements. If a value such as d is to be returned, this value is as- 
signed and used as the argument of a return( ) statement. 

A structure, for example, can look as follows: 


struct tag_name 


{ 


type declarations 


} struct_name; 


This architecture allows a tag name identifier, tag name, to be used with later 
definitions to define a structure that has similar characteristics. For example, the 
structure 


struct car 


{ 

char olds, chevy, pontiac; 
char accura, honda, mazda; 
char ford, lincoln, mercury; 
} car_type, *pcar_type; 


has as tag, car, and as structure name, car_type. The structure elements can be 
accessed using a period to offset the element from the structure name. In the struc- 
ture above the fifth element is accessed using 


car_type-honda = ... 
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contains some additional operators of less utility. The basic C data types are as 


follows: 


int 
long 
short 


unsigned = 


char 
float 
double 


integer (2 bytes); signed 
integer (4 bytes); signed 
integer (2 bytes); signed 
integer; zero or positive values 


unsigned int (2 bytes); 0 - 255 
unsigned long (4 bytes); 0 -—- 65535 
unsigned short (2 bytes); 0 - 255 


= character (1 byte) 38 38 


floating (4 bytes); -10307 - +10307 
floating (8 bytes); -10 - +10 


Within the OS/2 Kernel programming are a number of additional derived types 
used by Microsoft and IBM to expand the flexibility of OS/2. Some of these types 


are 
SEL 


PSEL 
SHANDLE 
BYTE 
PCHAR 
HFILE 
HSEM 
PUINT 
HVIO 
TID 


segment selector 

pointer to selector 

handle 

byte (char) 

pointer to character 

handle to file 

handle to semaphore 
pointer to unsigned integer 
handle to video context 
thread ID 


The addition of the Presentation Manager files adds many more derived types to the 


OS/2 inventory. 


The basic C storage classes are auto, external, static, and register: 


auto 


external 
static 


register 


generated with temporary duration within a module as a 
local class 


generated for all time as a global 
generated for all time but local in scope 


generated with temporary duration within a module as 
local and, if possible, associated with a CPU register 


The remaining topics to be briefly examined are functions, structures, unions, 
and pointers. This, then, will complete our look at the C syntax. The examples in 
the text are intended to provide additional insight into the C language and its appli- 
cability in the OS/2 programming environment. 
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When expression2 is evaluated TRUE, the associated statements are executed. Once 
the continue statement is executed, the processing jumps to the end of the loop 
without entering the second if structure regardless of whether expression3 is TRUE 
or FALSE. 

Table B.1 illustrates the major operators found in the C language. Table B.2 


TABLE B.1 C OPERATORS 
Operator Discussion 


() Grouping 

{} Executes all contained syntax 

++ Increment 

-- Decrement 

* Multiply 

Divide 

Add 

Subtract 

Less than 

Greater than 

Less than or equal 

Greater than or equal 

AND: logical 

OR: logical 

Equal: assignment 

Adds right-hand quantity to left hand 
Subtracts right-hand quantity from left hand 
Multiplies left hand by right hand 

Divides left hand by right hand 

Equal to: relational 

Not equal to: relational 

Modulus 

Modulus after dividing left hand by right hand 
Pointer: gives the value at the pointed address 
Pointer: gives the address of the variable 
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TABLE B.2. ADDITIONAL C OPERATORS 


Operator Discussion 

(type) Changes the type of a variable 
sizeof Returns the size in bytes of the variable 
-> Assigns a structure member 

’ Assigns a structure member 

! NOT: bitwise 

"y Takes one’s complement: bitwise 
& AND: bitwise 

* EXCLUSIVE OR: bitwise 

OR: bitwise 

Ds Conditional operator 

é< Left shift: bitwise 

5 


Right shift: bitwise 
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Here the alternate statements are executed when expression is FALSE. The case, 
switch, and default statements work together. Consider the following structure: 


switch (expression) 


{ 


case As 
statement #1; 
break; 

case B: 
statement #2; 
break; 

case Cs: 
statement #3; 
break; 


eee 


default: 
statement N; 
break; 


Here, if the value of expression takes on A, B, C, ... the corresponding case se- 
quence is executed. For all values not specified with a subsequent case statement, 
the default statement sequence is executed. 

The switch decision structure is used frequently in the Presentation Manager 
windows processing. We do not use this structure because the examples in this book 
did not involve multiple options. The break syntax was used to jump around subse- 
quent statements once the preceding statement had been executed. 

There are two statements that can be used to alter the sequence of processing. 
These are the jump statements, continue and goto. Consider the following loop: 


for(expression1) 
{ 
statements 
if{expression2) 
{ 
alternatel statements 
continue; 
} 
if(expression3) 
{ 
alternate2 statements 


} 
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for (k=1;k<=N;k++) 
{ 


statements 


} 
The while loop has the form 


while(expression) 


{ 


statements 


} 


where expression is returned as a TRUE or FALSE value. When TRUE the state- 
ments in the brackets are executed. Otherwise, the processing passes to subsequent 
statements, outside the brackets. 

The do while loop has an inverted structure with a test at the end of the loop: 


do 
{ 


statements 


} while(expression) 


Here statements are executed the first time through the loop and each subsequent 
time that expression evaluates TRUE. 

Decision structures are represented by the if, else, case, switch, and default 
statements. The if structure is of the form 


if (expression) 


{ 


statements 


} 


where a TRUE value for expression causes the statements to be executed. The else 
statement appears as follows, and is used in conjunction with the if statement: 


if (expression) 


{ 


statements 
} 
else 


{ 


alternate statements 


} 


B Microsoft C 
Compiler Version 5.1 


In Part Ill of this book the OS/2 Kernel was programmed using the C language. The 
specific C implementaion used was the Version 5.1 C Optimizing Compiler devel- 
oped by the Microsoft Corporation [1-3]. This compiler was one of the first that 
was made commercially available that would execute in the Protected Mode, so that 
it could be used with OS/2. Associated with the compiler is a Toolbox that is dis- 
cussed in Appendix C. This Toolbox provides high-level C interfaces to the OS/2 
API. These interfaces are suitable for use with the Microsoft C compilers and are 
provided as a set of .h include files. 

In this appendix we briefly review some of the C language syntax used in this 
book. We assume that the reader has a familiarity with C, hence we only provide 
this appendix for reference. The following categories are mentioned: 


1. Control structures 

2. Operators 

3. Data types and storage classes 
4. Other syntax _ 


The treatment of this appendix is similar to that given in Applied C: The IBM Mi- 
crocomputers [4]. 

The basic control structures fall into three categories: loops, decision structures, 
and jumps. Loops consist of the for, while, and do while syntax. The for loop struc- 
ture takes the form, for example: 
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TABLE A.11 (Concluded) 


Instruction Purpose Comments 
FENI/FNENI Enable inter- This instruction is the reverse of FDISI and 
rupts clears the interrupt mask in the control 
word. 
FLOCW source Load control This instruction replaces the current control 
word word with the word defined by the source 
operand. 
FSTCW/FNSTCW Store control This instruction writes the current control 
destination word word to the memory location defined by 
destination. 
FSTSW/FNSTSW Store status This instruction writes the current status word 
destination word to the memory location defined by destina- 
tion. 
FCLEX/FNCLEX Clear excep- Clears all exception flags, the interrupt request 
tions and busy flag. 
FSTENV/FNSTENV Store environ- Writes the basic status and exception pointers 
destination ment to the memory location defined by destina- 
tion. | 
FLDENYV source Load environ- Reloads the 8087 environment from the mem- 
ment ory area defined by the source. 
FSAVE/FNSAVE Save state Writes the environment and register stack to 
destination the memory location specified by the desti- 
nation operand. 
FRSTOR source Restore state Reloads the 8087 from the source operand. 
FINCSTP Increment stack Adds 1 to the stack pointer. 
pointer 
FFREE destination Free register Changes the destination’s tag to empty. 
FDECSTP Decrement stack Subtracts 1 from the stack pointer. 
pointer 
FNOP No operation Causes no operation. 
FWAIT Wait instruc- Causes the 8088 to wait until the current 8087 
tion instruction is complete before the 8088 ex- 


ecutes another instruction. 
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TABLE A.11 (Continued) 


Instruction Purpose Comments 


Integer compare This instruction compares ST(0) to the source 
operand, which is an integer-memory op- 
erand. 

Integercompare/ _This instruction is identical to FICOM except 


FICOM source 


FICOMP source 


pop the stack top, ST(0), is popped following 
the compare. 

FTST Test This instruction tests ST(O) relative to +0.0. 
The result of the test is returned in the condi- 
tion code of the status word: (C3, CO) = 
(0, 0) for ST positive, (0, 1) for ST negative, 
(1, 0) for ST zero, and (1,1) if ST cannot 
be compared. 

FXAM Examine The stack top, ST(0), is examined and the 
result returned in the condition code field 
as specified in the Version 2.0 Macro As- 
sembler Reference manual. 

Transcendental 

FPTAN Partial tangent This instruction calculates Y/X = TAN(z). 
The value z is contained in ST(O) prior to 
execution. Following execution, Y is con- 
tained in ST(1) and X contained in-ST(0). 

FPATAN Partial arc tan- This instruction calculates z = ARCTAN(Y/ 

gent X), where X is ST(O) and Y is ST(1). The 
result, z, is returned to ST(0). 

F2XM1 2 This instruction calculates 2* — 1, where x 
is taken from ST(O) and must be in the 
range (0, 0.5). The result is replaced in 
ST(0). 

FYL2X Y * log,(X) This instruction calculates Y * log,(X), where 
X is ST(O) and Y is ST(1). The stack top 
is popped and the result returned to the 
new ST(0). 

FYL2XP1 Y * log, This instruction is the same as FYL2X except 

(X + 1) 1 is added_to X. X must be in the range 
(0, 1 — V2/2). 
Constant 

FLDZ Load zero This instruction loads +0.0 in ST(0). 

FLD1 Load +1.0 This instruction loads +1.0 in ST(0). 

FLDP1 Load pi This instruction loads pi into ST(Q). 

FLDOL2T Load log,(10) This instruction loads log,(10) into the stack 
top, ST(O). 

FLOLZE Load log,(e) This instruction loads log,(e) into ST(0). 

FLDLG2 Load logj9(2) This instruction loads log, (2) into ST(0). 

FLDLN2 Load log,(2) This instruction loads log.(2) into ST(0). 

Control 
FINIT/FNINIT Initialize proc- This instruction accomplishes a hardware reset 
essor of the 8087. 
FDISI/FNDISI Disable inter- This instruction prevents the 8087 from issu- 


rupts 


ing an interrupt request. 
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Instruction 


FIDIV source 


FDIVR 


FDIVRP destination» 
source 


FIDIVR source 


Miscellaneous 
FSORT 


FSCALE 


FPREM 


FRNDINT 


FXTRACT 


FABS 


FCHS 
Comparison 
FCOM 


FCOMP 


FCOMPP 


Purpose 


Integer divide 


Real reversed 
divide 


Real reversed 
divide/pop 


Integer divide 
reversed 


Square root 


Scale 


Partial remain- 
der 


Round to integer 


Extract expo- 
nent/sig- 
nificand 


Absolute value 
Change sign 
Real compare 
Real compare/ 
pop 


Real compare/ 
pop twice 


App. A 


Comments 


This instruction divides the destination by the 
source and returns the quotient to the desti- 
nation. The destination is ST(O) and the 
source is an integer-memory operand. 


This instruction is identical with FDIV except 
the source is divided by the destination. 
The quotient is still returned in the destina- 
tion. 


This instruction is identical to FDIVP except 
the source is divided by the destination. 
The quotient is still returned in the destina- 
tion. 


This instruction is identical to FIDIV except 
the source is divided by the destination. 
The quotient is still returned in the destina- 
tion. 


This instruction replaces the content of ST(0) 
with its square root. 


This instruction interprets the value of the 
number contained in ST(1) as an integer. 
This value is added to the exponent of the 
number in ST(Q), which is equivalent to 
multiplying ST(0) by 2 raised to this integer 
power. 

This instruction takes the modulo of ST rela- 
tive to the number contained in ST(1). The 
sign is the same as that of ST(0). 


This instruction rounds ST(O) to an integer. 
The rules for rounding are determined by 
setting the RC field of the control word. 
RC = 00 (round to nearest integer), 01 
(round downward, 10 (round upward), and 
11 (round toward 0). 

This instruction reduces the number in ayo 
to a significand and an exponent for 80- 
bit arithmetic. 

This instruction yields the absolute value of 
ST(0). 

This instruction reverses the sign of ST(0). 


This instruction compares the source operand 
[which can be specified as a real-memory 
operand or implicit as ST(1)] and ST(O). 

This instruction is identical with FCOM except 
the stack top, ST(O), is popped following 
the compare. 

This instruction is identical with FCOM except 
the stack top, ST(0), and ST(1) are popped 
following the compare. 
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Instruction 


FISUB source 


FSUBR 


FSUBRP 


FISUBR source 


Multiplication 
FMUL 


FMULP destination» 
source 


FIMUL source 


Division 
FDI 


FDIVP destination» 
source 


(Continued) 
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Purpose 


Integer subtrac- 
tion 


Real reversed 
subtract 


Real reversed 
subtract/pop 


Integer reversed 


subtract 


Real multiply 


Real multiply/ 
pop 


Integer multiply 


Real divide 


Real divide/pop 
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Comments 


The destination, ST(0), has the source op- 
erand, an integer-memory operand, sub- 
tracted from it and the result is stored in 
ST(O). 


The destination is subtracted from the source 
and the result left in the destination. The 
operand configuration is the same as for 
FSUB. 


This instruction is the same as FSUBP except 
the destination is subtracted from the 
source. ST(O) still serves as the source op- 
erand. 


This instruction is the same as FISUB except 
the destination is subtracted from the 
source. The source is still an integer-mem- 
ory operand. 


This instruction multiplies the destination op- 
erand by the source and returns the product 
in the destination. The instruction can be 
executed with no operands [ST(O) is the 
implied source and ST(1) the destination], 
with the source specified as a real-memory 
operand and ST(0) the destination, and with 
both destination register and source register 
{one of which is ST(O)] specified. 


This instruction uses ST(O) as the source op- 
erand and another register as the destination. 
The product is returned in the destination 
register and the stack top popped. 


This instruction multiplies the destination by 
the source and returns the product in the 
destination. The destination is ST(O) and 
source is an integer-memory operand. 


This instruction divides the destination by the 
source and returns the quotient to the desti- 
nation. The instruction can be executed with 
no operands [ST(O) is the implied source 
and ST(1) the implied destination], with a 
source specified and ST(O) the implied desti- 
nation, and with a source [ST(0)] and desti- 
nation (another register) specified. 


This instruction divides the destination by the 
source and returns the quotient to the desti- 
nation. It then pops the top of the 8087 
stack. The source is the ST(O) register and 

- the destination operand is another stack reg- 
ister. 
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TABLE A.11 COPROCESSOR INSTRUCTION SET 
Instruction Purpose Comments 
Data transfer 
FLD source Load real Pushes the source data onto the top of the 
register stack, ST(0). 
FST destination Store real This instruction copies ST(O) into the indicated 


FSTP destination 


FXCH destination 


FILD source 


FIST destination 


FISTP destination 


FBLD source 


FBSTP destination 


Addition 
FADD 


FADDP destination» 
source 


FIADD integer- 
memory 


Subtraction 
FSUB 


FSUBP destination» 
source 


Store real/pop 


Exchange ST 
Load integer 


Store integer 


Store integer/ 
pop 


Load BCD 


Store BCD/pop 


Real addition 


Real add/pop 


Integer addition 


Real subtraction 


Real subtract/ 
pop 


destination (real), which can be a memory 
operand or register. 


This instruction copies ST(O) into the indicated 
destination and then pops ST(O) off the 
stack. 


This instruction exchanges ST(0) with the in- 
dicated destination. 


This instruction pushes the source data (in- 
teger) onto the top of the stack, ST(0). 


This instruction stores ST(O), the stack top, 
in the indicated destination, which must be 
an integer memory operand. 


This instruction stores ST(O), the stack top, 
in the indicated destination, which must be 
an integer memory operand, and then pops 
ST(O) off the stack. 


This instruction pushes the source, which must 
be a BCD number, onto the stack at ST(0). 


This instruction stores ST(0) as a BCD number 
at the destination and pops ST(Q) off the 
stack. 


This instruction can be used without operands 
[assumes ST(1) added to ST(O) with the 
result in ST(Q)], with a real-memory op- 
erand added to ST(0), or with explicit refer- 
ence to ST(Q) added to another register. 

The source is ST(Q) and the destination must 
be another stack register. The result is left 
in the alternate stack register used as the 
destination. 

The destination, ST(0), is added to the source, 
integer memory, and the sum returned in 
ST(O). 


This instruction can be used without operands 
[assumes ST(1) is the destination and ST(0) 
is subtracted from it with the result in 
ST(1)], with a real-memory operand sub- 
tracted from ST(O) and the result in ST(O), 
or with explicit reference to ST(O) and an- 
other register (the destination containing the 
result). 

The source, ST(O), is subtracted from the des- 
tination, another stack register, and the re- 
sult stored in the destination. 
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TABLE A.10 SPECIAL-PURPOSE MACRO OPERATORS 
Operator Description 


& Format: text&text. This operator concatenates text cr symbols. An example 
is 


TC1 MACRO x 
LEA DX + CHARR&X 
MOV AH; 9 
INT 21H 
ENDM 


Here a call TC1 A would load DX with a character start position CHARA. 


3 Format: ;;text. A comment preceded by two semicolons is not produced 
as part of the expansion when a MACRO or REPT is defined in an 
assembly. 


! Format: !character. Causes the character to be interpreted as a literal 
value, not a symbol. 


% Format: %expression. Converts expression to anumber. During expansion, 
the number is substituted for expression. Consider 


MACI MACRO x 
Li = x * 1000 
MAC2 ALA +X 
ENDM 
§ 


MAC2 MACRO Yoox 


PROD&XA DB ‘Production No. &X = &Y’ 
ENDM 
This yicids “‘PRODS DB ‘Production No. 5 = 5000,’ ”’ 


when called with MAC1 5. 
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TABLE A.9 
Pseudo-op 


«LFCOND 


+LIST and 


eXLIST 


40UT 


PAGE 


»SFCOND 
SUBTTL 

« TFCOND 
TITLE 


ENDM 
EXITM 


IRP 


IRPC 


LOCAL 


MACRO 


PURGE 


App. A IBM Macro Assembler/2 


(Concluded) 


Description 


This pseudo-op causes the listing of conditional blocks that evaluate 
as false. 


.LIST causes a listing of source and object code in the output assembler 
list file. .XLIST turns this listing off. These pseudo-ops can be 
used to selectively list code during the assembly of programs, 
especially long sequences of instructions. 

Form: %OUT text. This pseudo-op is used to monitor progress through 
a long assembly. The argument ‘‘text’’ is displayed, when encoun- 
tered, during the assembly process. 

Form: PAGE operand1, operand2. Controls the length (operand1) 
in lines and the width (operand2) in characters of the assembler 
list file. 


This pseudo-op suppresses the listing of conditional blocks that evalu- 
ate as false. 

Form: SUBTTL text. Generates a subtitle to be listed after each 
listing of title. 

This pseudo-op changes the listing setting (and default) for false 
conditionals to the opposite state. 


Form: TITLE text. This pseudo-op specifies a title to be listed on 
each page of the assembler listing. It may be used only once. 


ENDM is the terminator for MACRO, REPT, IRP, and IRPC. 


EXITM provides an exit to an expansion (REPT, IRP, IRPC, or 
MACRO) when a test proves that the remaining expansion is not 
needed. 

Form: IRP dummy, <operandlist>. The number of operands (sepa- 
rated by commas) in operandlist determines the number of times 
the following code (terminated by ENDM) is repeated. At each 
repetition, the next item in operandlist is substituted for all occur- 
rences of dummy. 


Form: IRPC dummy, string. This is the same as IRP except at each 
repetition the next character in string is substituted for all occur- 
rences of dummy. 


Form: LOCAL dummylist. LOCAL is used inside a MACRO struc- 
ture. The assembler creates a unique symbol for each entry in 
dummylist during each expansion of the macro. This avoids the 
problem of a multiply defined label, for example, when multiple 
expansions of the same macro take place in a program. 


Form: name MACRO dummylist. The statements following the 
MACRO definition, before ENDM, are the macro. Dummylist 
contains the parameters to be replaced when calling the macro 
during assembly. The form of this call is name parmlist. Parmlist 
consists of the actual parameters (separated by commas) used in 
the expansion. | 

Form: PURGE macro-name, . . . . PURGE deletes the definition 
of a specified MACRO and allows the space to be used. This is 
beneficial when including a macro library during assembly but 
desiring to remove those macros not used during the assembly. 
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TABLE A.9 (Continued) 


Pseudo-op Description 


END 


ENDP Form: procedure-name ENDP. Designates the end of a procedure. 

ENDS Form: structure-name ENDS or seg-name ENDS. Designates the end 
of a structure or segment. 

EQU Form: name EQU expression. Assigns the value of expression to 
name. This value may not be reassigned. 

= Form: label = expression. Assigns the value of expression to label. 
May be reassigned. 

EVEN EVEN ensures that the code following starts on an even boundary. 

EXTRN Form: EXTRN name:type, . . . . EXTRN is used to indicate that 
symbols used in this assembly module are defined in another 
module. 

GROUP Form: name GROUP seg-name,. . . . GROUP collects all segments 
named and places them within a 64K physical segment. 

INCLUDE Form: INCLUDE [drive] [path] filename.ext. INCLUDE assembles 
source statements from an alternate source file into the current 
source file. 

LABEL Form: name LABEL type. LABEL defines the attributes of name 
to be type. 

NAME Form: NAME module-name. NAME gives a module a name. It may 
be used only once per assembly. 

ORG Form: ORG expression. The location counter is set to the value of 
expression. 

PROC Form: procedure-name PROC [attribute]. PROC identifies a block 
of code as a procedure and must end with RET/ENDP. The attribute 
is NEAR or FAR. 

PUBLIC Form: PUBLIC symbol, . . . . PUBLIC makes symbols externally 
available to other linked modules. 

»RADIX Form: .RADIX expression. .RADIX allows the default base (decimal) 
to be changed to a value between 2 and 16. 

RECORD Form: recordname RECORD fieldname: width [=exp], . 

RECORD defines a bit pattern to format bytes and words for bit 
packing (see text). 

SEGMENT Form: segname SEGMENT [align-type] [combine-type] [‘class’] (see 
Chapter 3 for a discussion of this pseudo-op). 

STRUC Form: structure-name STRUC. STRUC is used to allocate and initial- 
ize multibyte variables using DB, DD, DQ, DT, and DW. It must 
end with ENDS. 

«CREF and This listing pseudo-op provides cross-reference information when a 

»XCREF filespec is indicated in response to the assembler prompt (CREF). 


»+LALL+-SALL > 
and .»XALL 


Form: END [expression]. END identifies the end of the source pro- 
gram, and the optional expression identifies the name of the entry 
point. 


It is the normal default condition. .XCREF results in no output 
for cross reference when in force. 

-LALL lists the complete macro text for all expansions. .SALL sup- 
presses listing of all text and object code produced by macros. 
.XALL produces a source line listing only if object code results. 
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TABLE A.9 APPLICATION-ORIENTED PSEUDO-OPS 


Pseudo-op 


ELSE 


ENDIF 
IF 


IFDEF 


IFDIF 


IFE 


IFIDON 


IFNB 


IFNDEF 


IF 1 


LEZ 


+ Z286C 


» 8086 


+8087 


ASSUME 


COMMENT 


DB 
DD 
DQ 
DT 


DW 


Description 


This pseudo-op must be used in conjunction with a conditional pseudo- 
op and serves to provide an alternate path. 

This pseudo-op ends the corresponding IFxxx conditional. 

Form: IF expression. When the expression is true, the code following 
this pseudo-op is executed; otherwise it branches to an ELSE entry 
point or an ENDIF. IF pseudo-ops can be nested. 

Form: IFB <operand>. This is the ‘‘if blank’’ pseudo-op and it is 
true if the operand has not been specified as in a MACRO call, 
for example. The code following the IFB is executed when operand 
is blank. Otherwise, the IP jumps to ENDIF. 

Form: IFDEF symbol. If symbol has been defined via the EXTRN 
pseudo-op, this is true and the code following the pseudo-op is 
executed. 

Form: IFDIF <operand1>, <operand2>. The code following this 
pseudo-op is executed if the string operand! is different from the 
string operand2. 

Form: IFE expression. The code following this pseudo-op is executed 
if expression = 0. 

Form: IFIDN <operand1>, <operand2>. The code following this 
pseudo-op is executed if the string operand! is identical to the 
string operand2. 

Form: IFNB <operand>. The code following this pseudo-op is exe- 
cuted if the operand is not blank. 

Form: IFNDEF symbol. The code following this pseudo-op is executed 
if the symbol has not been defined via the EXTRN pseudo-op. 
This pseudo-op is true if the assembler is in pass 1, and it is used 

to load macros from a macro library (as an example). 

This pseudo-op is true if the assembler is in pass 2, and it can be 
used to inform the programmer what version of the program is 
being used (when coupled with appropriate logic and a %OUT). 

This pseudo-op tells the assembler to recognize and assemble 80286 
instructions used by the IBM AT. 

This pseudo-op tells the assembler not to recognize and assemble 
80286 instructions. 

This pseudo-op tells the assembler to recognize and assemble 8087 
coprocessor instructions and data formats. 

Form: ASSUME seg-reg:seg-name, . . . . This pseudo-op tells the 
assembler which segment register segments belong to. 

Form: COMMENT delimiter text delimiter. COMMENT allows the 
programmer to enter comments without semicolons. It is not recog- 
nized by the SALUT program. 

Form: [variable] DB [expression]. It is used to initialize byte storage. 

DD has the same form as DB except it applies to doubleword quantities. 

DQ has the same form as DB except it applies to four-word quantities. 

DT has the same form as DB except it applies to 10-byte packed 
decimal. 

DW has the same form as DB except it applies to word quantities. 
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Operator 


MASK 


WIDTH 


NE 


Er 


LE 


GT 


GE 


AND » 
OR» and 
XOR 


NOT 


Type 


Record specific 


Record specific 


Arithmetic 
Arithmetic 
Arithmetic 
Arithmetic 


Arithmetic 


Arithmetic 
Relational 


Relational 
Relational 
Relational 
Relational 
Relational 


Logical 


Logical 
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Description 


The format of this operator is MASK recfield. It 
returns a bit mask for the field. The mask has 
bits set for positions included in the field and 0 
for bits not included in the field. 

The format of this operator is WIDTH recfield. It 
evaluates to a constant in the range 1 to 16 and 
returns the width of a record or record field. 

Returns the sum of two terms. Form: terml + 
term2. 

Returns the difference of two terms. Form: 
term] — term2. 

Returns the product of two terms. Form: term1 * 
term2. 

Form: term! MOD term2. It returns the remainder 
obtained by dividing term1 by term?2. 

Form: term! SHL term2. It shifts the bits of term1 
left by the amount contained in term2. Zeros 
are filled in the new bits. 

Same as SHL except the shift is to the right. 

Form: term1 EQ term2. Returns a value — 1 (TRUE) 
if term] equals term2, or 0 (FALSE) otherwise. 

Form: term1 NE term2. Returns a value — 1 (TRUE) 
if term! does not equal term2, or 0 (FALSE) 
otherwise. 

Form: term] LT term2. Returns a value — 1 (TRUE) 
if term] is less than term2, or 0 (FALSE) other- 
wise. 

Form: term1 LE term2. Returns a value — 1 (TRUE) 
if term]! is less than or equal to term2, or 0 
(FALSE) otherwise. 

Form: term] GT term2. Returns a value — 1 (TRUE) 
if term] is greater than term2, or 0 (FALSE) 
otherwise. 

Form: term! GE term2. Returns a value — 1 (TRUE) 
if term1 is greater than or equal to term2, or 0 
(FALSE) otherwise. 

These operators have the form term1 (operator) 
term2 and return each bit position as follows: 


term! bit 


term2 bit AND OR XOR 


Form: NOT term. This operator complements each 
bit of term. 
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TABLE A.8 


Operator 
PTR 


Seg-reg» 
Seg-name 


Grourp-name 


SHORT 


THIS 


HIGH 
LOW 
SEG 
OFFSET 


TYPE 


SIZE 


LENGTH 


SHIFT 
COUNT 
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Type 
Attribute 


Attribute 


Attribute 


Attribute 


Attribute 
Attribute 
Value returning 
Value returning 


Value returning 


Value returning | 


Value returning 


Record specific 


Description 


This operator has the form type PTR expression. 
It is used to override the type attribute (BYTE, 
WORD, DWORD, QWORD, or TBYTE) of a 
variable or the attribute of a label (NEAR or 
FAR). The expression field is the variable or 
label that is to be overridden. 


The segment override operator changes the segment 
attribute of a label, variable, or address expres- 
sion. It has three forms: 


seg-red:addr-expression 
seg-namezaddr-expression 
grouP-name:addr-expression 


This operator is used when a label follows a JMP 
instruction and is within 127 bytes of the JMP. 
It has the form JMP SHORT label and changes 
the NEAR attribute. A pass 2 NOP instruction 
is avoided. 


The form of this operator is THIS type. The operator 
produces an operand whose segment attribute is 
equal to the defining segment, whose offset equals 
IP, and a type attribute defined by ‘“‘type.’’ For 
example, ‘“AAA EQU THIS WORD’”’ yields an 
AAA with attribute WORD instead of NEAR 
(if used in the same code segment). 


This operator accepts a number/address argument 
and returns the high-order byte. 


This operator accepts a number/address argument 
and returns the low-order byte. 


This operator returns the segment value of the vari- 
able or label. 


This operator returns the offset value of the variable 
or label. 


For operand arguments, this operator returns a value 
equal to the number of bytes of the operand. If 
a structure name, it returns the number of bytes 
declared by STRUC. If the operand is a label, 
it returns 65534 (FAR) and 65535 (NEAR). 


This operator returns the value LENGTH x TYPE. 


For a DUP entry, LENGTH returns the number 
of units allocated for the variable. For all others 
it returns a 1. 


This operator is used with the RECORD pseudo- 
op and is the name of the record field. The format 
of RECORD is: recordname RECORD field- 
name: width. The value of fieldname, when used 
in an expression, is the shift count to move the 
field to the far right within the byte or word. 
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TABLE A.7 SYSTEMS-ORIENTED 80286 AND 80386 INSTRUCTIONS 


Instruction 


ARPL dest.» source 


CLTS 


LAR dest.» source 


LGDT/LIDT m 


LLDT source 


LMSW source 


LSL dest.» source 


LTR source 
SGDT/SIDT m 


SLOT dest. 


SMSW dest. 


VERR/VERW source 


STR dest. 


Purpose 


Adjust RPL field of 
selector 


Clear Task Switched 
Flag 


Load access rights byte 


Load Global/Interrupt 
Descriptor Table 
register 


Load Local Descriptor 
Table register 


Load Machine Status 
Word 


Load segment limit 


Load Task Register 


Store Global/Interrupt 
Descriptor Table 
register 

Store Local Descriptor 
Table register 


Store Machine Status 
Word 


Verify a segment for 
reading or writing 


Store Task Register 


Comments 


If the RPL field of the selector (protection 
bits) in dest. is less than the RPL field 
of source, ZF = 1 and the RDL field of 
dest. is set to match source. 


The Task Switch Flag is in the Machine 
Status Word and is set each time a task 
change occurs. This instruction clears that 
flag. 

Destination contains a selector. If the associ- 
ated descriptor is visible at the called pro- 
tection level, the access rights byte of 
the descriptor is loaded into the high byte 
of source (low byte = 0). 


m points to 6 bytes of memory used to pro- 
vide Descriptor Table values (Global and 
Interrupt). This instruction loads these ta- 
bles into the appropriate 80286 registers. 


Source is a selector pointing to the Global 
Descriptor Table. The GDT should, in 
turn, be a Local Descriptor Table. The 
LDT register is then loaded with source. 


The Machine Status Word is loaded from 
source. 


If the Descriptor Table value pointed to by 
the selector in destination is visible at 
the current protection level, a limit value 
specified by source is loaded into this 
descriptor. 


The Task Register is loaded from source. 


The contents of the specified Descriptor Ta- 
ble register are copied to 6 bytes of mem- 
ory pointed to by m. 

The Local Descriptor Table register is stored 
in the word register or memory location 
specified by destination. 


The Machine Status Word is stored in the 
word register or memory location speci- 
fied by destination. . 

Source is a selector. These instructions de- 
termine whether the segment correspond- 
ing to this selector is reachable under the 
current protection level. 


The contents of the Task Register are stored 
in destination. 
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TABLE A.6 ADDITIONAL 80386 APPLICATION INSTRUCTIONS 


Instruction 


BSF dest.» source 


BSR dest.» source 


BT base» offset 


BIC base» offset 


BTR base,» offset 


BTS base» offset 


CWDE» CWD 


CMPSD 


CDQ 


INSD 


LODSD 
MOVSD 


MOVSX 


MOV2ZX 


OUTSD 
POPAD 


POPFD 


PUSHAD 


PUSHFD 


SCASD 


SETcc dest. 


SHLD dest.» Count 


SHRD dest.» Count 


STOSD 


Purpose 


Bit scan forward 


Bit scan reverse 
Bit test 


Bit test and comple- 
ment 


Bit test and reset 


Bit test and set 


Convert word to dou- 
bleword 


Compare double- 
words 


Convert doubleword 
to quadword 


Input 

Load string operand 

Move data from 
string to string 

Move with sign- 
extend 


Move with zero- 
extend 
Output 


Pop all general regis- 
ters 


Pop stack into 
EFLAGS 


Push all general reg- 
isters 


Push EFLAGS onto 
stack 


Compare string data 


Byte set on condition 


Double-precision- 
shift left 


Double-precision 
shift right 
Store string data 


Comments 


The source word (doubleword) is scanned for a 
set bit and the index value of this bit loaded 
in destination. Scanning is from right to left. 


Scans as in BSF but reverse order. 


This instruction loads the bit value from base 
at offset in the base, into the CF register. 


This instruction loads the bit value from base 
at offset in the base, into the CF register, and 
complements the bit in base. 


This instruction loads the bit value from base 
at offset in the base, into the CF register, and 
resets the bit to 0. 


This instruction is identical to BTR, but the re- 
sulting bit is set to 1. 


This instruction converts the signed word in AX 
to a doubleword in EAX. 

This instruction compares ES: [EDI] with 
DS: [ESI]. 

Converts the signed doubleword in EAX to a 
signed 64-bit integer in the register pair 
EDX:EAX by extending the sign into EDX. 

Input from port DX to ES:[EDI] (doubleword). 

Load doubleword DS:[ESI] into EAX. 

Move doubleword DS:[{ESI] to ES:[EDIT]. 


Move byte to word, byte to dword, and word 
to dword with sign extend. 


Move byte to word, byte to dword, and word 
to dword with 0 extend. 
Output dword DS:[ESI] to port in DX. 


Pops the eight 32-bit general registers. 
Pops the 32-bit stack top into EFLAGS. 


Pushes the eight 32-bit general registers onto 
the stack. 


Pushes the EFLAGS register onto the stack. 


Compares dwords EAX and ES:{EDI] and up- 
dates. EDI. 


Stores a byte (equal to 1), if cc, the condition, 
is met (following a compare, for example). 
Otherwise, a value of 0 is stored at the destina- 
tion. 


The destination is shifted left by count. 
Same as SHLD but shift is to the right. 


Store EAX in dword ES:[EDI] and update EDI. 
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TABLE A.5 ADDITIONAL 80286 APPLICATION INSTRUCTIONS 


Instruction 


BOUND dest. »source 


ENTER immediate-word » 
immediate-byte 


IMUL dest. simmediate 


INS/INSB/INSW 
dest.-stringsport 


LEAVE 


OUTS/OUTSB/OUTSW 
Port;source-string 


POPA 


PUSH immediate 


RCL dest. »CL 


RCR dest. »CL 


ROL dest. »CL 


ROR dest. »CL 


SAL/SHL dest. »CL 


SAR dest. »CL 


SHR dest. CL 


Purpose 


Check array index 
against bounds 


Make stack frame for 
procedure parame- 
ters 


Integer immediate 
multiply 

Input from port to 
string 


High-level procedure 
exit 
Output string to port 


Pop all general regis- 
ters 


Push immediate onto 
stack 


Rotate left through 
carry 

Rotate right through 
carry 

Rotate left 


Rotate right 

Shift arithmetic left/ 
shift logical left 

Shift arithmetic right 


Shift logical right 


Comments 


This instruction ensures that an index (des- 
tination) is above or equal to the first 
word in the memory location defined 
by source. Similarly, it must be below 
or equal to “‘source + 2.”’ 


‘‘Immediate-word’’ specifies how many 
bytes of storage to be allocated on the 
stack for the routine being entered. ‘‘Im- 
mediate-byte’’ specifies the nesting 
level of the routine within the high-level 
source code being entered. 


Does a signed multiplication of destination 
by an immediate value. 


Transfers a byte or word string from the 
port numbered by DX to ES:DI. The 
operand dest.-string determines the type 
of move: byte or word. 

Executes a procedure return for a high- 
level language. 

Transfers a byte or word string from mem- 
ory at DS: DI to the port numbered by 
DX. 

Restores the eight general-purpose regis- 
ters saved on the stack by PUSHA. 

This instruction pushes the immediate data 
onto the stack. 

Same as RCL for 8088 except count can 
be 31. 

Same as RCR for 8088 except count can 
be 31. 

Same as ROL for 8088 except count can 
be 31. 

Same as ROR for 8088 except count can 
be 31. 

Same as 8088 instructions except count 
can be 31. 

Same as 8088 instruction except count can 
be 31. 


Same as 8088 instruction except count can 
be 31. 
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TABLE A.4. THE COMPARE INSTRUCTION GROUP 


Instruction Purpose Comments 
CMP destination, source Compare two This instruction causes the source to 
operands be subtracted from the destination; 


however, only the flags are af- 
fected. The destination remains un- 


changed. 

CMPS destination-str | Compare byte or The source string (with DI as an index 
source-str word string for the extra segment) is subtracted 
(CMPSB) from the destination string (which 
(CMPSW) uses SI as index). Only the flags 


are affected and both DI and SI 
are incremented. A typical se- 
quence of instructions could be 


MOV SI» OFFSET AAA 
MOV DI» OFFSET BBB 
CMPS AAA» BBB 


Table A.5 contains additional instructions specific to the 80286 microproces- 
sor. Table A.6 contains similar instructions for the 80386 microprocessor. Both of 
- these microprocessors are designed to operate in Protected Mode. The computer used 
in writing this book was a PC AT with a 6-MHz throughput rate, as opposed to the 
4-MHz clocks associated with the IBM PC. Expansion to the PS/2 systems should 
yield even faster performance than the 80286-based system used here. Table A.7 
presents the system-oriented instructions available for the 80286 and 80386. These 
instructions are not normally accessible by the applications programmer. 

Table A.8 contains the Macro Assembler operators available to the program- 
mer, Table A.9 contains the pseudo-operations available to the Macro Assembler 
programmer, and Table A.10 contains a set of operators to be used with the macro 
pseudo-op. 

Table A.11 illustrates the coprocessor instruction set. These instructions begin 
with the letter “F” and most rely on the use of the coprocessor stack registers, ST(0) 
through ST(7), for implementation. These stack registers serve as the general-purpose 
registers for the coprocessor. Usually, ST(O) serves as the source register and ST(1) 
as the destination, particularly in implicit instructions such as FADD when used 
without operands. 
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Instruction 


JE short-label 
(JZ) 


JG short-label 
(JNLE) 


JGE short-label 
(JNL) 


JL short-label 
(JNGE) 


JLE short-label 
(JNG) 


JMP target 
JNC short-label 


JNE short-label 
(JINZ) 
JNO short-label 


JNB short-label 
(JPO) 


JNS short-label 


JO short-label 


JP short-label 
(JPE) 


JS short-label 


Purpose 


Jump if equal/ 
if zero 


Jump if greater/if 
not less or equal 


Jump if greater or 
equal/if not less 


Jump if less/if not 
greater or equal 


Jump if less or 
equal/if not 
greater 


Jump 
Jump if no carry 


Jump if not equal/ 
if not zero 


Jump if no over- 
flow 

Jump if no parity/ 
if parity odd 

Jump if no sign/if 
positive 

Jump on overflow 

Jump on parity/ 
if parity even 

Jump on sign 
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Comments 


If the last operation to change ZF set this 
flag (gave a result of 0), JE will cause 
a jump to occur. This is a short-label 
jump. 

If ZF = 0 and SF = OF, the JG instruction 
will cause a jump to short-label. This 
instruction is used with signed operands. 

This instruction is the same as JG except 
ZF is not considered. If SF = OF, the 
jump occurs. This is a short-label instruc- 
tion with signed operands. 

If SF # OF, the JL instruction will result 
in a jump. This instruction is short-label 
with signed operands. 

If ZF = 1 or SF # OF, the JLE instruction 
yields a short-label jump. The instruction 
is used with signed operands. 

This is a direct and unconditional jump. 

If CF = 0, this instruction yields a short- 
label jump. 

If ZF = 0, this short-label jump will occur. 


If OF = 0, this short-label jump will occur. 
If PF = 0, this short-label jump will occur. 
If SF = 0, this short-label jump will occur. 


If OF = 1, this short-label jump will occur. 
If PF = 1, this short-label jump will occur. 


If SF = 1, this short-label jump will occur. 
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Table A.3 presents the jump instruction group. These instructions are used to 
achieve execution control within the langauge. They accomplish this by providing 
the capability to change the instruction execution sequence based on the outcome of 
various tests. These tests can be performed by various instructions that change the 
state of flags in the flags’ register. Table A.4 illustrates the compare instructions, 
which serve as a basis for accomplishing such testing. These instructions change the 
flags without changing the source or destination. 


TABLE A.3) JUMP INSTRUCTION GROUP 


Instruction Purpose Comments 
JA short-label Jump if above/ This jump is used in conjunction with the 
(JNBE) if not below or carry and zero flags. If either or both 
equal are set, no jump occurs. Suppose two 


operands are compared; then if the desti- 
nation is greater than the source (above) 
CF = ZF = 0 and the jump occurs. 

The jump is within — 128 to +127 bytes 
(short-label) and unsigned operands are 


used. 
JAE short-label Jump if above or This jump is similar to JA except only the 
(JNB) equal/if not be- carry flag is examined. If a previous com- 
low pare, for example, is performed and the 


destination is greater or equal to the 
source (above or equal), CF = 0 and 
the jump occurs. This is a short-label 
instruction with unsigned operands. 


JB short-label Jump if below/if This jump is the opposite of JAE. If the 
(JNAE) not above or carry flag is set, the jump will occur. 
(JC) equal/if carry Suppose a previous compare is per- 


formed and the destination is less than 
the source (below); CF = 1 and the jump 
occurs. This is a short label instruction 
with unsigned operands. 


JBE short-label Jump if below or This jump is the same as JB except it also 
(JNA) equal/if not takes place if the zero flag is set (below 
above or equal). It is short-label with unsigned 

operands. 
JCXZ short-label Jump if CX is zero Suppose an instruction sequence causes the 


count register (CX) to decrement. When 
CX reaches 0, control would transfer to 
the short-label after execution of JCXZ. 
This is a short-label jump. 
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Instruction 
DAS 


I/O 
IN acc, port 


OUT port, acc 


Miscellaneous 
XCHG dest,src 
XLAT src-table 


Purpose 


Decimal subtract 
adjust 


Input byte/word 


Output byte/word 


Exchange 
Translate 


Comments 


Adjust for decimal subtraction. 


The byte/word contents of port are 
loaded into AL/AX. 

The contents of the accumulator are 
sent to port output. 


Exchanges the source (src) with dest. 

BX is loaded with a table address. AL 
contains a location number (byte) in 
the table and this byte is replaced 
in AL. 


family of microprocessors. These instructions are grouped by category: 


ray 


. Arithmetic 
Logical 
Move 
Load 
Loop 
Stack 
Count 

. Flags 
Shift 
Rotate 
Store 

. String 

. Convert 

. Control 

» ASCII 

. Decimal 
1/O 
Miscellaneous 


So PAAR SR Wh 


femdom fk femek ech fk fk fk pk 
SCNINADMN BR WNE OS 
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TABLE A.2 (Continued) 


Instruction Purpose 
RCR dest,cnt Rotate right through 
Carry 
ROL dest,cnt Rotate left 
ROR dest,cnt Rotate right 
Store 
STOS dest-str Store byte or word 
string 
SAHF Store AH in flags 
String 
REP Repeat string opera- 
tion 
REPNE Repeat string opera- 
tion 
SCAS dest-str Scan byte or word 
string 
Convert 
CWD Convert word to 
doubleword 
CBW Convert byte to 
word 
Control 
CALL target Calls a procedure 
RET Return from a pro- 
cedure 
ESC ext-opcode, Escape 
src 
LOCK Lock bus 
NOP No operation 
WAIT Wait 
ASCII 
AAA ASCII adjust for ad- 
dition 
AAD ASCII adjust for di- 
— vision 
AAH ASCII adjust for 
multiply 
AAS ASCII adjust for 
subtraction 
~ Decimal 


DAA Decimal add adjust 
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Comments 


Rotates dest right in wrap-around fash- 
ion cnt bits where cnt is in CL. 


Same as RCL except the high-order 
bit rotates into CF as well as the 
low-order bit. 


Same as ROL except to the right. 


Transfers a byte (word) from AL (AX) 
to the location pointed to by DI. 


Transfers the value in AH to the flags 
register. 


Causes the string operation that 
follows to repeat until CX = 0, 
ZF = 1. 

Same as REP except ZF = 0. 


Subtracts the dest-str from AL (AX) 
one byte at a time and affects the 
flags. 


Sign extends AX into DX. 


Sign extends AL into AX. 


Calls a procedure (target). 
Returns control to the calling routine. 


Initiates the ext-opcode with operand 
src. 


Closes the bus to access. 
A do-nothing operation. 


A bus cycle state used for synchroniza- 
tion. 


Adjusts the sum for an ASCII numeri- 
cal value following addition. 

Adjusts the quotient for ASCII numeri- 
cal value following division. 

Adjusts the product for ASCII numeri- 
cal value following multiplication. 

Adjusts the difference for an ASCII 
numerical value following subtrac- 
tion. 


Adjust for decimal addition. 
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TABLE A.2 (Continued) 


Instruction Purpose 
LAHF Load AH from flags 
LDS dest,src Load data segment 
register 

LEA dest,src Load effective ad- 
dress 

LES dest,src Load extra segment 
register 

Loop 

LOOP short-label Loop until count 

complete 


LOOPE short-label Loop if equal 


LOOPNE short- Loop if not equal 
label 
Stack 
POP dest Pop word off the 
stack 
POPF Pop flags off the 
stack 
PUSH src Push word onto the 
stack 
PUSHF Push flags onto the 
stack 
Count 
DEC dest Decrement 
INC dest. Increment 
Flags 
CLC Clear carry flag 
CLD Clear direction flag 
CLI Clear interrupt flag 
CMC Complement carry 
| flag 
STC Set carry flag 
STD Set direction flag 
STI Sets interrupt flag 
Shift 
SAL dest,cnt Shift arithmetic left 
SHL dest,cnt Shift logical left 
SAR dest,cnt Shift arithmetic 
right 
SHR dest,cnt Shift logical right 
Rotate 
RCL dest,cnt Rotate left through 


carry 


273 


Comments 


Transfers the flags to AH. 

Loads a 32-bit address into DS and 
dest (offset). 

Transfers the offset of src to dest. 


Loads a 32-bit address into ES and 
dest (offset). 


Control is transferred to short-label if 
CX # 0 and CX is decremented. 

Same as LOOP but control transfers 
if ZF = 1, as an additional require- 
ment. 

Same as LOOPE except ZF must equal 
0. 


Transfers a word from the stack 
(pointed to by SP) to dest. 


Transfers the word from the stack top 


to the flags register. 
src is placed on the stack top. 


The flags register 1s loaded onto the 
top of the stack. 


Subtract one from dest. 
Add one to dest. 


Sets Cf = 0. 
Sets DF = 0. 
Sets IF = 0. 


Changes setting of CF. 


Sets CF = 1. 
Sets DF = 1. 
Sets IF = 1. 


Shifts dest cnt bits left. CL contains 
cnt. 

Same as SAL. 

Same as SAL except shift if to the 
right. 

Same as SAR. 


Rotates dest left in wrap-around fash- 
ion cnt bits where cnt is in CL. 
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3.6. 


3.7 


3.8. 
3.9. 


3.10. 


3.11. 
3.12. 


3.13. 


memory area such as a shared segment defined using 
\SHAREMEM\SDAT . DAT 
where the path is common to both processes. 


RAM semaphores are a good candidate for intertask communications when each 
thread is within the same process. When conducting interprocess communications, 
system semaphores provide a good method for synchronization because they share a 
common system memory area and can be passed back and forth. 


The macro @pushs loads a 32-bit address for parm on the stack. The macro @pushd 
loads the 32-bit contents of the double-word parameter parm onto the stack. The 
fourth parameter of @DosWriteQueue must contain a pointer value, and the address 
of this the double word containing this value is not of interest. 


By clearing the semaphore using @DosSemClear. 


There could be a segment protection violation, as both processes contend for the 
speaker. 


A pipe was used to pass buffered data directly. The queue, on the other hand, was 
used to pass pointers to buffers. The queue employed a shared memory area allo- 
cated by @DosAllocSeg, whose buffer address was passed via the queue. 


See Table 3.1. 


A shared segment is allocated with @DosAllocShrSeg and is used when two or more 
processes need to access a common buffer in interleaved or multiple asynchronous 
fashion. The fact that both have simultaneous access must be regulated using sema- 
phores, for example. A giveable segment, on the other hand, would be used when a 
process desires to write to a common segment and then release the segment so that 
another process can access the “given” segment. 


Process 1 

read_hdl | dw ? 

write_hdl dw ? 

buf_flag dw 256 ;for example 

bytes written dw ? 

msize dw ? 

ssell dw ? 

shrname db ‘\SHAREMEM\SDAT1.DAT’ , 0 
@DosAllocShrSeg  msize,shrname,msell allocate segment 
@DosMakePipe read_hdl, write_hdl, buf_flag ;Create pipe 


@DosCreateSem eee ; Synchronize 
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@DosWrite write_hdl,message,length,bytes written ;Transfer 


@DosSemSet ese ;set semaphore 
@DosExecPgm ees ;execute child 

@DosWait ee swait child completion 
Process 2 


shrsel dw ? 

shrname db ‘\SHAREMEM\SDAT1.DAT’,0 

read hdl ... 

bytes_read ... 

@DosOpenSem ... ;open semaphore 
@DosGetShrSeg... sget shared segment 


eee 


sload read handle and message length from shared segment 
buffer 


ee 


@DosRead read_hdl, buffer, length, bytes_read ;read buffer 


@DosSemClear ... ;Clear semaphore 


Process 1 
q. hdl dw ? 
q name db ‘\QUEUES\QDAT.DAT’ ,0 


@DosCreateQueue q_hdl,... ;create queue 
@DosExecPgm... sexecute child 
@DosReadQueve q_hdl,... ;read queue buffer 


;transfer message using 32-bit queue pointer to buffer 


eee 


@DosFreeSeg... ;free allocated segment (process) 
@DosCloseQueue... ;close queue 

Process 2 

q_hdl dw ? 


q_ name db ‘\QUEUES\QDAT.DAT’ ,0 


Answers To Problems 325 


3.15. 


3.16. 


qw dw 0 

qv dd 0 

q.rr dw 0 

@DosOpenQueue ... sopen queue 
@DosAllocSeg... syallocate segment 


sload segment with message 


@DosGiveSeg... ;get read selector 
@DosWriteQueuel... ;write address to queue 
@DosFreeSeg qw ;free allocated segment 


@DosCloseQueue... 


The intraprocess thread appears as a FAR entry point within the same process seg- 
ment. An interprocess thread appears as a FAR call to an entry point in a new seg- 
ment, and it must be started with DosExecPgm. 


The calls 


@DosAllocSeg 
@DosReAllocSeg 


actually create and reallocate global memory space. This memory can exist as vir- 
tual addresses (on disk) or as actual data RAM. The call 


@DosSubAlloc 


subdivides an existing segment into smaller blocks of local memory. This call returns 
a block offset to be used as the start of the memory block. No consideration of pre- 
vious writes to the segment is made; hence a block can overwrite a memory area if 
not properly handled. A recommended procedure is to suballocate the memory seg- 
ment as early as possible, thereby obtaining a block offset from which to work. 


Chapter 4 


4.1. 


4.2. 


When IBM and Microsoft developed the two versions of the Toolkit, they modified 
the structures and calling sequences between them. Calling the physical screen buffer 
in Version 1.0 required a structure PhysBufData. In the Version 1.1 this structure 
was renamed _VIOPHYSBUF and the structure members have different tags between 
versions. Hence many of the Version 1.1 Toolkit entities require slightly different no- 
menclature than that of Version 1.0. 


Many of the Standard C I/O library functions have been defined under Microsoft C 
Optimizing Compiler Version 5.1 to run as reentrant routines. Hence these library 
routines are callable in the usual fashion from Protected Mode. 
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4.3. 


4.4. 


4.5. 


4.6. 


4.7. 


4.8. 


4.9. 


4.10. 
4.11. 


4.12. 


4.13. 


Answers To Problems 


All formal parameters specified as type int need not be type specified in the formal 
parameter list. Hence, when passing parameters, only types other than int need be 
specified. 


The input value x is of int type, hence can be signed. The range of such signed 
variables is [-32,768, 32,768]. Had this parameter been of type double or float, a 
much greater range of values would be permissible. 


The normal C local stack calling convention starts with the Nth parameter and con- 
tinues to load the stack down to parameter 1. The API services require conventional 
loading from parameter 1 to N. In the Toolkit a type APIENTRY is defined using 
the pascal convention, which reorders the formal parameters on the stack from 1 to 
N. 


The code 
CHAR FAR *ptr; 


defines a FAR pointer, ptr, which points to a byte value using a 32-bit address. The 
code 


CHAR FAR *shrname = “\\SHAREMEM\\SDAT1.DAT”; 


defines a FAR pointer, shrname, which points to a string value using a 32-bit ad- 
dress and associates the string value with this 32-bit address. 


This function generates a full 32-bit address for a FAR call. The variables sel and 
off correspond to selector and offset, respectively, and must be obtained separately. 


This declaration associates a FAR pointer address of 0xB8000 with a BYTE value 
specified as the structure element PVBPrt2.pBuf. Note that this structure element is 
specified as part of the physical buffer structure WIOPHYSBUF. The value in ques- 
tion is the start address (32-bit) for the physical screen buffer. 


The return from sinQ is double precision; hence the defining relation should be 
y = (float)(sin(2. * PI * t)); 


The dot attribute for wdot() is 1, and the dot attribute for uwdot() is 0. 


The column values represent horizontal increments, and the row values represent ver- 
tical increments. 


This is the character code for putting the Epson dot matrix printer (FX-85) into 
graphics mode. The values 0x1B and Ox4V specify 


ESC k 


and 64 is the difference between 256 and 320. Here the “1” indicates one block of 
256 columns plus “64,” to get 320 columns in the printer graphics mode. The ESC k 
indicates that the printer must go to graphics mode. 


This sends the Epson FX-85 printer the command 
ESC A 8 
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4.14. 
4.15. 


4.16. 


4.17. 


4.18. 


4.19. 


which changes the printer output to case 8/72-inch spacing for lines. This removes 
any extra vertical spacing that might appear in the output and ensures that the eight 
dots of vertical spacing will butt together as each vertical set of pins is executed for 
each line (25 vertical lines of eight pins per line). 


RAM semaphores. 


The calls all employ type definitions for the formal parameters unless the parameters 
are of basic integer type (such as INT, UINT, USHORT, SHORT). 


One process must establish the semaphore, open the second process, and wait until 
the second process is complete. The second process maintains synchronization by 
executing with the first process blocked until 


DosSemClear ( ) 

is issued by the second process. This allows the first process to cease being blocked 
by 

DosSemWait ( ) 


and continue execution beyond this instruction. Threads are handled in identical fash- 
ion. 


To pass the pipe read handle, read_hdl, to the second process, where it is used to 
locate the pipe buffer and transfer the pipe message using 


DosRead ( ) 


The thread’s stack is separate from the calling thread’s stack. Hence the compiler 
will detect an overflow condition because the second thread’s stack is “outside” the 
stack originally defined for the overall process. To avoid compiler errors with the 
Microsoft C Optimizing Compiler Version 5.1, for example, a compiler option of -Gs 
must be used. 


The programs have been debugged and it is assumed that no error checking is 
needed intrinsically. Good form would retain such error checking when dynamic er- 
rors can creep in. For clarity, we have avoided them in the code dynamics. 


4.20. The points | 
(x,y,z) = (1, 0, 0) 
(0, 1, 0) 
(0, 0, 0) 
(0, 0, 1) 
4.21. From the library cgraph.lib. 
Chapter 5 
5.1. Load the routine as a run-time dynamic linker library (DLL). 


5.2. 


The dynamic link library (.dll) executable module is generated from a group of ob- 
ject modules as 


link (group object modules), 
(-dll module),,(libraries),(.def module) 
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5.3. 
5.4. 


5.5. 


5.6. 


5.7. 


5.8. 


5.9. 


5.10. 


5.11. 


Answers To Problems 


Here the definition file must start with the LIBRARY keyword. Next, the .lib file is 
created from 


implib (.lib file) (.def module) 

This definition file is the same one used earlier to define the .dll module. 
The return address offset. 

It appears in the definition file with LIBRARY, not NAME. 


EXPORTS are the names of routines contained in a DLL which will be available to 
be called by other modules. IMPORTS are the names of external routines to be used 
by the DLL. 


The two services needed are 


DosLoadModule 
DosGetProcAddr 


The first is required to load the run-time .dll file, which must be specified in the ini- 
tial calling program. This is the calling program’s link with the DLL. The second is 
needed to specify the DLL procedure entry point so that a simple FAR call to this 
entry point can be made. 


You would choose a flowchart because it illustrates the dynamic decision-oriented 
performance of the program. There are several types of flowcharts: literal and func- 
tional. The former spell out each individual programming step and tend to be very 
detailed. Functional flowcharts are more desirable and address program activity in a 
functional sense; that is, each block constitutes a major activity in the sequence of 
program flow, and this activity usually consists of many program steps. A Structure 
Chart merely illustrates the subordinate relationships among the program components. 
This device is most useful for providing the user with an overview of the program 
and a general picture of the major modules appearing in the program. 


The dominant characteristic of a C function is a single entry and exit point and a 
single return value. These features serve to make the program structure very orderly 
with a downward flow of activity to the code instead of the varied branching found 
in programs typified by FORTRAN code, for example. In FORTRAN programs, the 
unrestricted use of GOTOs and conditional branching frequently makes following the 
program flow difficult. 


C programs can efficiently use global variables when large array components of da- 
tabases are to be manipulated. In this case the use of arrays as local variables would 
greatly expand the stack area and result in inefficient memory allocation. The diffi- 
culty with using global variables in any implementation is that external modules that 
call such variables frequently lose track of the time history of the variables. By treat- 
ing variables as locally defined, the complete time picture of the performance of the 
variable is available in the accessing module. 


This is accessible only through the Presentation Manager, which did not become 
available until OS/2 Version 1.1 was issued. 


Three-dimensionally the x-axis points out of the image away from the plane of the 
CRT. Hence a two-dimensional display, such as a CRT, can only illustrate the image 
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of a three-dimensional surface as it is projected onto such a two-dimensional display. 
This projection is achieved by setting one of the coordinate sets equal to zero. 


5.12. Some of the hidden facets appearing in the three-dimensional surface of Figures 5.19 
through 5.23 actually have positive direction normals to the facet surface. Hence 
these surfaces, even though hidden, will not satisfy the criterion that the normal 
points into the plane of the CRT. 


5.13. This equation has the form 


using 
3 5 
snu =u - % + & _ 
This becomes 
2 
P _ wv ue iS: Ae 
fing A E a1 + 5 ~ [=A 


5.14. This routine must be called before setting the CGA mode because it prints a request 
to the text screen (asking for the name of the data file). 


5.15. The selector, MMI, would no longer be referenced. 


Index 


@define, 42 

@pushs, 42 

@pushw, 42 
@DosAllocHuge, 121 
@DosAllocSeg, 96 
@DosAllocShrSeg, 105 
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@DosClose, 46 
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@DosGiveSeg, 116 
@DosKillProcess, 106 
@DosMakePipe, 152 
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@DosOpenSem, 130 
@DosRead, 156 
@DosReadQueue, 159 


@DosReallocSeg, 116 
@DosSemClear, 130 
@DosSemSet, 130 
@DosSemWait, 130 
@DosSubSet, 126 
@DosWrite, 46 
@DosWriteQueuel, 160 
@VioGetPhysBuf, 56 
@VioScrLock, 56 
@VioScrollUp, 54 
@VioScrUnlock, 56 
@VioSetMode, 56 
@ViowrtTTY, 132 
@kbdStringIn, 56 
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accessing huge segments, 119 
accessing a memory segment, 112 
accessing a shared segment, 105 
access rights byte, 10 

algorithm development, 248 
align-type, 44 
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API.LIB, 40 combine-type, 44 

APIENTRY, 176 Common Programming Interface, 31 
API Services, 20 complexity metrics, 241 

API type definitions, 176 connecting dot graphics lines, 74 
Apple McIntosh display, 17 CONNL2, 74 

Application Programming Interface, 2 C operators, 296 

assembler addressing modes, 271 coprocessor instructions, 288 
assembler to C template, 222 core loop, 16 

assembler instructions, 272 C parameter passing, 224 
assembler macro operators, 282 C program to generate threads, 199 
assembler pseudo-ops, 284 C program structure, 171 
ASSUME pseudo-op, 44 creating a DLL, 231 

asynchronous execution, 29 creating huge segments, 119 
automatic segments, 229 creating a memory segment, 96 


creating a pointer, 182 
creating a process, 140 
B creating a shared segment, 105 
creating a thread, 130 
C screen graphics routines, 182 


base pointer, 176 CSEG, 63 

bbox.asm, 82 current protection level, 18 
bboxl.asm, 82 cursor, 17 

BIOS, 19 

bitmap, 32 

bitwise operators, 248 

boot record, 17 D 

boxprtl.asm, 69 

branching in C, 245 DATA1. 223 

bus, 5 7 : 


data management, 14 

data structures, 248 

db pseudo-op, 45 

C definition library file, 29 
DESCRIPTION, 228 

descriptor cache register, 94 
descriptor privilege, 95 

descriptor table, 10 

destruction of a memory segment, 95 


Cartesian unit vector, 253 
C compiler, 167 
C control mechanisms, 243 


cdecl, 33 device drivers, 14 

CGA graphics mode, 54 direct memory access, 53 
cgraph.lib, 183 disk access, 204 
changing segment size, 115 dja.c, 214 

child process, 30 dlinkl.asm, 233 

child process in C, 192 DOS, 1 

ckthread.c, 199 DosAllocShrSeg(), 192 
C language syntax, 293 doscalls.inc, 41 

class, 44 DOS Compatability Mode, 1 
clipboard, 32 DosExecPgm(), 197 
CODE, 228 _ DosExit(), 197 

code segment privilege, 95 DosKillProcess(), 197 


CodeView, 2 : 
Color Graphics Adapter, 51 DosMakePipe(), 192 


Index 


DOS partition, 6 
DosRead(), 197 
DosWrite(), 195 

Dow Jones program, 214 
dw pseudo-op, 45 
dynamic linking, 29 
dynamic-link libraries, 29 
dynl.asm, 232 

dynll.def, 231 

dynll. dll, 231 

dynil. lib, 231 

dyn2.asm, 237 
dyn22.def, 236 
dyn22.lib, 237 
dyn33.def, 237 
dyn33.lib, 237 


E 


Enhanced Graphics Adapter, 51 

erasable programmable read only 
memory, 6 

error checking, 250 

EXECUTEONLY, 228 

EXECUTEREAD, 228 

Explicit Load and Call DLL, 227 

EXPORTS, 229 

Extended Edition, 2 
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facet, 252 

facet3d.c, 262 

Family.API, 35 

Far call, 43 

firmwave, 6 

flagword, 12 

form, 246 

fprintf(), 218 

Full-screen command prompt mode, 2 
function macros, 300 


G 


gates, 11 
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gen3d.c, 255 

giveable segment, 160 

global descriptor table, 18 

global space, 9 

gphrout.c, 182 

GRAPHICS.COM, 62 

GRAPHLIB.LIB, 72 

GROUP pseudo-op, 45 

guidelines on C module 
development, 240 


H 


handles, 17 

heap, 227 

HEAPSIZE, 229 

hidden lines, 253 
higher-level language, 19 
hugeseg.asm, 122 

huge segments, 29 


IBM PS/2, 1 

icon, 31 

IF1 pseudo-op, 45 

implib, 231 

import library utility, 231 
IMPORTS, 230 

include files, 168 

INDEX field, 10 

initialization routine dyninit.obj, 236 
Intel CPU, 1 

interfacing assembler to C, 221 
interrup address space, 9 
Interrupt Service Routine, 14 
intersegment transfer, 11 
IOPL, 18 

IOPS, 30 

iterative loops, 242 


K 


keyboard services, 313 
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L 


latch, 6 

Idarray, 63 

ldmem, 112 

levels of protection, 3 
LIBRARY, 228 

linear subspaces, 8 
lineh, 61 

linker, 28 

LINK utility, 231 
loader, 28 
LOADONCALL, 228 
Load on Call DLL, 227 
local thread stack, 16 
LS138 demultiplexers, 6 
LS245 transcriber, 6 


machine code, 44 

Machine Status Word, 12 

macro assembler, 43 

MAKE file, 173 

MAKEP function, 180 

Memory Management, 93 

memory-management registers, 8 

message boxes, 32 

metafile, 32 

Microsoft C Compiler Version 5.1, 2 

Microsoft Windows, 17 

mixed-language programming, 222 

Mixed Object Document Content 
Architecture, 32 

modal dialog boxes, 32 

modaless dialog boxes, 32 

Modular Code, 87 

module size, 241 

mouse, 17 

mouse services, 313 

multitasking, 29 

multi-threaded applications, 188 

musical scale program, 225 
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NAME, 228 
NEAR procedure, 173 


NONSHARED, 228 
nos2512.asm, 106 
nos261.asm, 111 


O 


object-oriented tools, 251 
optimizing execution speed, 222 
option/CO, 198 
option-Gs, 198 
option-Zi, 198 
OS2P2.EXE, 149 
overlapped windows, 32 
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PAGE pseudo-op, 45 
pascal calling convention, 176 
pel, 51 

physical address, 4 
physical memory space, 6 
physical selector, 61 
pipes, 14 

pipes in C, 192 
pipest.asm, 152 

pixel, 51 

polling model, 14 
pprtscr.c, 182 


preemptive time-slicing dispatcher, 14 


PRELOAD, 228 

pre-loaded DLL, 227 
Presentation Manager, 17 
printer control characters, 48 
printer graphics mode, 51 
printer program, 46 

printf, 172 

print head weights, 48 


privileged instruction exception, 18 


process, 14 

processor extension, 12 
program design language, 244 
program page numbers, 310 
program to plot two lines, 56 © 
program segment prefix, 48 
Protected Mode features, 20 
PROTMODE, 228 

prtscr, 61 

prtwave.c, 182 
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pseudo-code, 87 
pseudo-op, 44 
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QUEUECL.EXE, 157 
queues, 14 


R 


random access memory, 2 
random box program, 136 
reentrant, 29 

registers, 4 

representation of tetrahedron, 201 
requested privilege level, 10 
return values, 250 

rotating tetrahedron, 200 
rotation matrices, 201 
rotation of a point, 200 
rotetra.c, 205 

RS-233C adapter, 5 
run-time loading, 28 
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scalesl.asm, 226 

scanf, 172 

screen buffer, 42 

screen buffer physical memory, 51 
screen buffer pixel placement, 51 
scr_Id, 61 

scr_ldm, 96 

segment address translation registers, 10 
segment descriptors, 10 

segment selector, 9 

segmented memory, 8 
SEGMENTS, 228 

semaphore, 14 

semaphores in C, 192 
sequentially defined code, 243 
SHARED, 228 

shared memory segments, 14 
shared segments in C, 192 
SHAREMEM, 105 

simplified OS/2 architecture, 15 
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sine work program, 180 
single-thread, 1 
slopeln.asm, 74 

stack, 19 

stack pointer, 176 
STACKSIZE, 228 

Standard Edition 1.0, 1 
Standard Edition 1.1, 2 
Standard Mode (80x25), 54 
stdio.h, 171 

Strategy routine, 14 
Structure Chart, 34 
Structured Programming, 87 
Structured Query Language, 2 
STUB, 228 

Style, 244 

suballocating memory, 125 
subcalls.inc, 41 

swave.c, 180 

synchronous execution, 30 
sysmac.inc, 41 

Systems Application Architecture, 31 


T 


table indicator, 10 

task manager, 14 

task state segments, 11 

task switch, 18 

temporary screen buffer, 104 
termination panel, 32 

tetra.c, 201 

_TEXT, 223 

thread, 14 

three dimensional surface, 251 
tiled windows, 32 

timhist.c, 213 

TITLE pseudo-op, 45 
Toolkit, 30 

Top-Down Design, 87 
twoln.asm, 69 

twolnm.asm, 96 


V 


VEDIT PLUS, 2 
Video Graphics Adapter, 51 
VioGetCurPos, 41 
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VIOMODEINFO structure, 177 
VioScrollUp(), 197 
VioWrtTTY(), 197 

virtual memory, 9 


W 


waitf, 60 
wdot, 56 
Windows Software Development Kit, 31 


X 


xadiskr.c, 260 
xscale.c, 261 


Z 


zero termination, 105 
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2.7. 


2.8 


2.9 


2.10 


2.11. 


2.12. 


2.13. 


2.14. 


2.15. 
2.16. 


kbd_buf db 80 

1kbd_buf dw $-kbd_buf 

iowait dw 0 

kbdhdl equ 0 

freq dw 1000 

dur dw 5000 

@KbdStringiIn kbd_buf,1lkbd_buf,iowait,kbdhdl 

@DosBeep freq,dur 

Yes, all calls to the API can be made in full form, where each push and pop, as 


well as EXTRN declaration, is stated explicitly according to the rules of OS/2. The 
toolkit simply provided a set of assembler .inc files and C .h files that facilitated 
usage of the API services through very functional macros. 


The key assumption is that segment selectors can be treated as segment addresses. 
Since the 80286 accesses segments using the selectors, the selector value must reside 
in a segment register. The address is then calculated in the usual Protected Mode 
fashion, where the segment selector acts as a segment address. The use of segment 
override addressing, such as 


es: [bp] 


simply permits specification of an address in the usual fashion, where the segment 
selector is made to correspond to the physical segment address when VioGetPhysBuf 
is exercised. 


They represent FAR locations because the entry points are called from external API 
modules, hence a 32-bit address must be specified. 


No hierarchy should have a single child subordinate to a parent. The box 310 should 
be absorbed in 300. 


The command is 
@DosWrite dev_hand,in_buffer5,bytesin3,bytesout 
where the undefined parameter is 


in _buffer5 db 1BH,41H,0CH 


It is intuitive that they cannot be preempted by an OS/2 task switch, or the possibil- 
ity of losing data from the device would occur. 


To access the screen buffer (physical) properly, the screen must be locked; hence if 
scr_Id is to load scr_buffer with the screen context, it must be locked. If prtscr is 
executed when the screen is locked, it could dominate access time for the physical 
display buffer. Hence the program should load a temporary buffer, release the screen 
context, and then begin the print operation. 


Ten complete raster segments. 


The DosExitCritSec corresponds to exit of a critical section of execution for a thread 
and returns control to a process. This could be used, for example, when an _ inde- 
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2.17. 


Answers To Problems 


pendent thread has a particular piece of code that must execute prior to any other 
operation for the parent process. Then it would be desirable to monitor and ensure 
that this code executed, before continuing. Clearly, this could be dynamic and change 
with the active chronology of execution. 


DosExit is used to terminate an application and return to OS/2. All other returns 
NEAR or F. 


Chapter 3 


3.1. 


3.2. 


3.3. 


3.4. 


3.5. 


The drivers mentioned operate from the kernel, level 0. They must originate here 
because they have to be protected ahead of all other code. We cannot have a disk- 
write preempted in the middle, nor can we tolerate “jerky” mouse cursor movement 
as the mouse position changes. 


The macro calls admittedly remove a layer of detail from the program code. This 
layer would tend to expand the code by a factor of 4 to 7. All the pushes to the 
stack have been suppressed prior to each API call and the call takes on the form of 
a higher-level-language (HLL) function call. The data area tends to expand consid- 
erably with all the macro parameter definitions, but the actual executable code re- 
mains compact. This requires the programmer to develop a general familiarity with 
the macro calls at the level of the IBM Programmer’s Toolkit or Appendix C of this 
book. Once this familiarity has developed it is a very easy matter to read the result- 
ing “structured” code and follow the flow of execution. Hence maintenance becomes 
an easy task. Clarity (of how the code executes) is also paramount, and much more 
so under the macro call format. The macro calls do, however, inhibit debugging in 
that the in-line code is missing. If the user prints a copy of the list file with macros 
expanded, tracing the source code is still an easy matter. In general, these approaches 
tend to be a matter of preference based on the programmer’s orientation. We favor 
the HLL appearance of the code. It makes functional performance of the code the 
primary mechanism to be emphasized. Expansion of the in-line code makes it more 
obscure from a functional viewpoint but easier (and essential) to debug. 


For the segment to be sharable, bit 0, to be sharable through @DosGiveSeg, or bit 1, 
to be sharable through @DosGetSeg, must be set in the flags word (the third pa- 
rameter in the calling list). Bit 2 of this same flags word must be set if the segment 
is to be discardable. 


The write to the huge segment must use the proper selector. When crossing the 64K- 
byte boundary the program must access a new but contiguous selector. 


There must be some common link between the two processes. Usually, this is a 
common element name such as 


\SEM\SDAT.DAT 
or 
\QUEUES\QDAT.DAT 


which appears in both processes and is the same. The system then provides the con- 
nection. Alternative to this is the passing of a selector or printer in a common 
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